Skip to main content
Version: 1.7.1

FormW9

1. How to create Form W-9s using TaxBandits APIs?

TaxBandits API allows recipients to fill in their Form W-9 information using a secure portal and e-Sign. There are two ways to do this:

  • Use the RequestbyEmail endpoint to have payers (you) trigger the request. If you have the names and email addresses of recipients, send in these details in the request. We will trigger an email with a unique URL link to the recipients. Recipients will click the URL link, fill in their Form W-9 information, e-sign, and submit the form.
  • Use the RequestbyURL endpoint to have recipients trigger the request. It could be as simple as a click of a button or link on your website. You must ensure the request initiated has a unique identity of the recipient in tag PayeeRef. API will generate a unique URL for each request. Recipients will click the URL link, fill in their Form W-9 information, e-sign, and submit the form. This is a POST method, and recipient details such as Name and Address, if passed in the request, will be prefilled on Form W-9.

Also, when you create forms using the TaxBandits API, we allow access to these forms through the TaxBandits application. Use your API credentials to sign-in to your TaxBandits account. Now, W9s can also be created directly in the TaxBandits application. You can pull up these forms along with the ones created using the API through the List Endpoint.

2. You have two endpoints - RequestbyUrl and RequestbyEmail for FormW9 API. Which one should we use?

There are 2 ways to create Form W-9s using the TaxBandits API. The request can be triggered by either the payer or the recipients themselves. Depending on who initiates the W9 request, you may use the appropriate endpoint.

Use RequestbyEmail endpoint when the payer triggers the W9 request. You have the names and email addresses of your recipients. Send them through this endpoint. We will trigger individual emails with a link to fill in their W9 information, e-sign, and submit the form.

Use RequestbyURL endpoint when you want your recipients to initiate the W9 request. When they do that, a unique URL is generated by the API. Using this URL, the recipient enters their W9 information, e-signs, and submits the Form W-9. Pass the recipient details such as Name and Address in the request to prefill them.

The widespread usage is when you have a vendor management portal. When a vendor logs on to the portal, you can present this dynamic link for the vendors to complete the W9. This can be completely white-labled and also iframed optionally.


3. Some of our recipients may be Foreign Individuals who should be filing Form W-8BEN instead of FORM W-9. How do we use your API services to cater to our requirements?

Use FormW9 API service ONLY if all your recipients are U.S. citizens or beneficial owners receiving compensation for services performed in the United States. Likewise, use FORMW8BEN API when all your recipients are foreign individuals. However, if you want your recipient to choose either Form W-9 or Form W-8BEN based on whether they are foreign individuals or not, use WhCertificate API instead.

The GetURL endpoint of WhCertificate returns a unique URL which allows your recipient to decide the form to file. They can choose Form W-9 or Form W-8BEN with a click of a button, fill in their information, e-sign, and submit the form.


4. How do I use your TIN Matching services when requesting W9s?

TaxBandits API provides the capabilities to do a TIN Matching based on the W9 information submitted by your recipients. Whether it's the RequestbyEmail or RequestbyURL endpoint, you may opt for TIN Matching by setting the IsTINMatching flag to TRUE. By doing so, when your recipients fill in their W9 information, e-signs and submits the Form W-9, TaxBandits will validate the recipient’s Name, TIN, and Type of TIN with the IRS.

Even if TIN Match fails, the recipient is created in your account. Alternatively, you can do the TIN Matching for the recipient later when you create their 1099s.


5. Suppose we don’t do the TIN Matching when requesting W9s. Can it be done later?

Of Course! You can use the Request endpoint of TINMatchingRecipients API. When W9s are created, references to Recipient ID are available. Pass these as an array in your request. TaxBandits will send the TIN Matching requests to the IRS. You will be notified via Webhook on the statuses. The Webhook payload will have data such as the Recipient Name, TIN, Type of TIN, and Status of TIN Matching.

Do note that TaxBandits restricts the number of attempts you make for TIN Matching. The Parameter NumOfAttemptsRmng will have the number of TIN Matching attempts remaining.


6. How do I force TIN Matching failure in the Sandbox region?

To simulate a TIN Match error in the Sandbox region, use any TIN that ends with 000. Then use the List endpoint of FormW9 to pull up the W9 and TIN Matching Statuses of your recipients under a business.


7. How do I get the list of recipients whose W9s failed TIN Matching?

When you opt for TIN Matching when requesting W9s for your recipients, TaxBandits will validate the recipient’s Name, TIN, and Type of TIN with the IRS. Once the W9 creation is completed, the TIN Matching process against IRS kicks-in. Use the Status endpoint to know the statuses of W9 creation and TIN Match for a recipient.

The Status object contains both these statuses. Looks for ones with W9Status = ‚ÄėCompleted‚Äô and TINStatus - ‚ÄėFailed‚Äô.


8. We need to get the recipients to sign their W9s. Do we print copies and have them physically sign?

Not required! When you use the TaxBandits API to create W9s, you don't have to worry about taking printouts and having your recipients sign the form. Instead, TaxBandits allows recipients to electronically sign their Form W-9s after filling their W-9 information using a secured portal.


9. We have the information to generate W9s and would like to use your services. How do I do that?

It is best when your recipients can fill in their W-9 information, e-Sign, and Submit their Form W-9. Our W9 generation capabilities allow just that. Use the RequestbyEmail or RequestbyURL endpoint depending on whether you want TaxBandits to trigger emails to your recipients and have them fill in their information, or have recipients trigger the request and fill in their information.

Do note that RequestbyURL endpoint provides capabilities to prefill the Recipient Name and Address fields on Form W-9. Your recipients only need to fill in their TIN, e-sign, and submit the form.


10. Is there a provision for recipients to edit a W9 they submit?

TaxBandits API does not have an explicit endpoint to edit a completed W9. Every time the RequestbyURL endpoint is triggered, a unique URL is generated by the API whether the request has the same PayeeRef or not. The Recipient then clicks this URL, fills in their W9 information, and submits the form. Based on the PayeeRef, TaxBandits will link the W-9s against the recipient. That means multiple W9s can be generated for a recipient, but only the latest one will be associated with the recipient.

Alternatively, you may use the RequestbyEmail endpoint that triggers the email to your recipient with a link that allows them to fill in their W9 information and submit the form.


11. How do you handle duplicate W 9 requests from our recipients? They may want to make some corrections and resubmit the request.

There is no restriction on the number of W-9 submissions a recipient can make. TaxBandits API associates a W-9 to a recipient based on the unique identifier PayeeRef in the request. As long as the PayeeRef is the same, the last generated Form W-9 will be associated with the recipient.


12. What is "PayeeRef"? What’s its significance in a W9 request?

PayeeRef is a unique identifier for each recipient completing the Form W-9. It accepts a String value type and could be the vendor id, contractor number, or even their email address. TaxBandits will associate the request against a recipient based on the PayeeRef. For any future references of the recipient in the API, you can use this identifier or the RecipientId.


13. Does the API handle business validations before W9 creation? Where do I look for information related to business validation errors?

TaxBandits API handles Form W-9 creation differently. No business rule validations are done at the API end. The W9 form is presented to your recipients to fill in their W9 information, e-sign, and submit. Business validation and error checks are done when they fill in the form details. Form W-9s are generated after it gets past these checks.

Since the validations are done at the page level and not at the API level, the ability for you as payer to look for information related to business validation errors during W9 creation does not arise.


14. How do I get a copy of recipient W9?

In both RequestbyEmail and RequestbyURL endpoints, your recipients may fill their W9 information, e-sign, and submit their FORM W-9 at different times. For TaxBandits to notify you of any W9 submission, the opening of form, or its completion, you must configure Webhook for W9 Status in your API Console account. By setting up the Callback URL, TaxBandits will tell you when the recipient W9 is generated.

Use the Status endpoint with W9Status = ‚ÄėCompleted‚Äô to know if the recipient W9 is ready for download. Then use the Get endpoint, and the URL to download the Form W-9 will be available under PdfUrl.


15. Does the W9 generation happen instantly when the request is received? If not, how do we know when it's ready?

No, it does not happen instantly. There are various intermediate statuses from the time the W9 URL is generated for a recipient until the Form W-9 is finally generated. Use the Status endpoint to know at what stage the W9 creation request is in. For example, the recipient may not have entered the W9 form or is yet to submit the Form W-9.

TaxBandits provides the provision to configure Webhook for W9 Status in your API Console account. By setting up the Callback URL, TaxBandits will tell you when the recipient W9 is generated.


16. Is there a way we are notified when recipients fill in their W9 information and submit the request?

Yes. To do that, you must configure Webhook for W9 Status in your API Console account. Click here on how to do that. By setting up the Callback URL, TaxBandits will be able to tell you the status of the W9 request at various stages, right from the Order Creation, Submission of Form W-9 until the completion of Form W-9.

To download a Form W-9, use the Status endpoint with W9Status = ‚ÄėCompleted‚Äô to know if the recipient W9 is ready for download. Then use the Get endpoint, and the URL to download the Form W-9 will be available under PdfUrl.


17. We see in Webhook payload, the W9 information is posted back. Is there a way to have the TINs masked?

Yes. To do that, check the Mask TIN option when you set up the Webhook for W9 Status in the API Console account. By doing so, the TINs will be masked in the Response JSON that posts back the W9 information.

Below is a sample Response JSON with masked TINs. Also, note that the PdfUrl tag has the link to the generated Form W-9.

Webhook Log


18. Is it possible to prefill the recipient’s name and address on Form W-9? That way, it would make it easier for the recipient to fill only their TIN, e-Sign, and Submit?

Yes. RequestbyURL endpoint is a POST method that allows you to pass optional information such as Recipient Name and Address. When the recipient clicks the link to open the Form W-9, this information will be pre-filled by TaxBandits. The recipient only needs to enter the TIN, e-Sign, and Submit the form.


19. How do we whitelabel the page our recipients use to enter their W9 information? We want to show our Business logo on the page.

The RequestbyURL endpoint allows customization of the page that your recipient sees. Pass the URL to your business logo in the request and render it on the page your recipients see. Also, URLs to where we need to redirect upon submission or cancelation of the form can be passed as parameters.

"Customization": {    "BusinessLogoUrl": "//logo.clearbit.com/spotify.com?size=80"  },  "RedirectUrls": {    "ReturnUrl": "https://example.com",    "CancelUrl": "https://example.com"  }}

20. We want recipients to fill in their W-9 details and submit the form. Which Webhook URL should we configure?

Endpoint FormW9 allows recipients to fill in their W-9 details, e-sign, and submit the form. Notification will be sent to the client through Webhook once recipients submit Form W-9.  However, if you want the option for recipients to choose either W9 or W-8BEN, use WhCertificate instead.

For endpoint FormW9, choose the Event Type Form W9 Status Change to configure webhook URL. Notification will be sent to this Webhook URL once recipients submit Form W-9. The payload will have W9 details, status of TIN matching if opted for, and the URL to download the completed form optionally made available.

21. How do I get the list of recipients whose W9s failed TIN Matching?

When you opt for TIN Matching when requesting W9s for your recipients, TaxBandits will validate the recipient’s Name, TIN, and Type of TIN with the IRS.  Once the W9 creation is completed, the TIN Matching process against IRS kicks-in. Use the List endpoint to know the statuses of W9 creation and TIN Match for a recipient.

The List object contains both these statuses. Looks for ones with W9Status = ‚ÄėCompleted‚Äô and TINStatus - ‚ÄėFailed‚Äô.

22. We need to get the recipients to sign their W9s. Do we print copies and have them physically sign?

Not required! When you use the TaxBandits API to create W9s, you don't have to worry about taking printouts and having your recipients sign the form. Instead, TaxBandits allows recipients to electronically sign their Form W-9s after filling their W-9 information using a secured portal.

23. How will we know if a TIN Matching is successful or not?

Use the Status method in these endpoints to get the TIN Matching status of a recipient. You will have to provide the PayeeRef and BusinessIds. If the TIN Matching is success, then the status would return as ‚ÄúSuccess‚ÄĚ.

Below are the available TIN statuses:

  • ‚Äč‚ÄčOrder Created - Recipient completed the Form W-9 and a TIN Matching order created in Taxbandits. The TIN Matching request is yet to be sent to the IRS.
  • Under Process - Our system has batched the TIN Requests and is queued for IRS submission.
  • Sent to Agency - The order has been sent to the IRS for TIN verification and TaxBandits is waiting for the response from the IRS. Usually the IRS takes one business day to complete the TIN verification process.
  • Success - Recipient‚Äôs Name and TIN combination matches with the records in the IRS database.
  • Failed - Recipient‚Äôs Name and TIN combination does not match with the records in the IRS database.
  • Canceled - The TIN Matching request for a recipient was canceled by the client.

24. TIN Matching failed for a few recipients. How do we have them fill in Form W-9 and resubmit them?

PayeeRef is the unique identifier for each recipient completing the Form W-9. Whether it is FormW9/RequestByURL or FormW9/RequestByEmail, TaxBandits will associate W-9 submissions based on PayeeRef. Do opt for IsTINMatching = True for TaxBandits to  validate the newly submitted recipient’s Name, TIN and TINType with the IRS.

In TaxBandits, the recently submitted W-9 will be associated with the recipient, although the history of prior W-9s will be available.

25. When recipients complete and submit their Form W-9 or Form W-8BEN, how are they notified?

You must configure the appropriate Webhook(For Form W-9 use, Form W-9 Status Change and for Form W-8BEN, use Form W-8BEN Status change) in the developer console. Notification will be sent to this Webhook URL once recipients sign and submit Form W-9. The webhook payload includes the recipient data, including the Name, Address, Country of citizenship, and TIN number along with the link to download the completed form.

26. What is the time frame for the TINmatching process?

When requesting a Form W-9 from the recipient, you can opt for TIN Matching. Once the recipient completes their Form W-9, TaxBandits will validate the Name and TIN on the Form W-9 against the IRS records. Verification usually takes one or two days.

27. Is there a way to hide/remove the download option in W-8BEN/W-9 for security reasons?

You will have SSN in completed Form W-8BEN/W-9. Due to security reasons, If you want to hide/remove the download button for completed Form W-8BEN/W-9, you can request, and our internal team will help with the request.