Extend your software with TaxBandits IRS E-file API Integration

Skip to main content
Version: 1.6.1

FormW9

1. What are my options 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"
  }
}