Skip to main content
Version: 1.6.1

RequestByUrl

To report to the IRS payments greater than $600 made to vendors during the tax year, 1099s are filed. Before reporting,  as a payer, you must collect from your vendors details such as payee name, TIN, Type of TIN, address etc using Form W-9. Now, it is recommended you do a TIN Match before filing 1099s. Catching them early allows you to avoid hefty penalties from filing invalid 1099s.

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. If TIN matching fails, you can request a new Form W-9 from the recipient.

Below we discuss the solution to acquire signed W-9s from your recipients using the TaxBandits API. A viable solution is to have recipients fill their W-9 information, e-sign, and submit the form. 

Here’s how W9 endpoint may be used:

  • Call the Auth method to get the access token. This access token must be supplied in the request header as the ‘Bearer‘ token. Refer OAuth 2.0 Authentication for more information on JWT authentication and how to integrate with the subsequent requests.
  • RequestByUrl will provide the unique URL that can be opened on the client's diet to complete the form. Whereas RequestByEmail will send an email to the recipient with the link. The link will redirect the user to a portal (That can be white-labeled) to complete the W-9 form.
  • Delete method  is used to delete a particular W-9 request or a submission. If there are multiple W-9s requested in a Submission, all the W-9 records under the submission will be deleted.
  • Status method returns statuses of form submission.
  • Use the method List to list the W-9 under a particular business. The W-9 can be filtered based on the W-9 Statuses and Date Range. 
  • Get method returns the information submitted by the payee along with the link to download the completed W-9.
  • Setup W9 Status Change Webhook. When recipients fill, e-sign, and submit the form, webhook will post an URL for the completed W-9 form.

RequestByUrl

To complete the Form W-9, TaxBandits will supply the URL that can be opened on its own or embedded into a web page or native app. To get the URL, you will have to send a request to our API with a unique Payee Reference such as vendor id, contractor number or a random number or even an email address (This will be used to identify the recipient for future references) and some business identifier (Business Id or TIN).

The popular use case is where you have a portal for your vendors and you can place a link to collect the W9 information. Each vendor who logs in will get a unique url embedded page to complete their W9.

How does this work?

  1. Like any other TaxBandits API Endpoint, the first step is to call the Auth method to get the access token. This access token must be supplied in the request header as the ‘Bearer‘ token.Refer to OAuth 2.0 Authentication for more information on JWT authentication and how to integrate with the subsequent requests.

  2. The second step is to call the FormW9/RequestByURL API endpoint. If you are trying the embed this link into your web page, this endpoint must be called before you load the page. You will need to supply the following parameters:

    • Access Token in the header (Will be supplied by TaxBandits or generated using TaxBandits OAuth authentication API)
    • Payee Reference (Unique information that identifies the Recipient). The Payee Reference can be anything that uniquely identifies the recipient such as Vendor id, contractor number or a random number or even the recipient email address (This will be used to identify the recipient for future references)
    • Business Identifier (Business Id or TIN) - Business Identifier (Business Id or TIN) - This is used to identify and save the W9 against a particular Business. Refer to the Business endpoint to learn more about creating a Business in TaxBandits and retrieving the Business Id. In TaxBandits, you can uniquely identify a business using either by its TIN or the TBS generated Business Id. You can also define a ‘Default Business’ in the TaxBandits Application and skip sending the Business Identifier along with the request. See below for more examples.
    • Recipient Name and Address (Optional) - If you want to pre-fill the Name and Address of the recipient on the W-9 form, you can send them as a parameter in the request.
    • Business Logo and Callback URLs (Optional) - You can add the business logo on the Form W-9 completion page and also set the callback redirection for recipient form completion/cancel.
  3. TaxBandits will generate an unique URL and will send the link in the response, which must then be embedded into the page for the recipients to click. When clicked, this link will show the Form W-9 with built-in validations. There is also an electronic signature pad that allows the recipient to sign electronically.

  4. Once the recipient completes and signs the Form W-9, you will be notified via Webhook. The Webhook payload will have the W-9 recipient data such as the Name, Address and EIN/SSN along with the link to download the completed Form W-9

  5. If IsTINMatching is set ‘TRUE’, TaxBandits will validate the recipient Name, TIN and TINType against the IRS database. The TIN Matching status of the recipient (Success or Failed) will be posted on the same Webhook URL configured for Form W-9 status change.

If the Name and TIN given by the recipient does not match with the IRS database, the W-9 will become invalid and you have to request a new Form W-9 from the recipient.

Refer Form W-9 webhook to know more about webhook set up and sample payload

POST FormW9/RequestByUrl

Request Body

FieldTypeDescription
RequesterObjectCollects the Requestor identifier. TIN or TBS Business Id or PayerRef. If neither is supplied, the default Business will be assumed as the Requester.
    PayerRefStringOptional Unique payer identifier assigned by the client while requesting the payer information using the endpoint Business/RequestByURL.
Size Range: 1-50
    BusinessIdGuidOptional TaxBandits Unique Business Identifier. This ID is generated by `TaxBandits after you create a business in your account using the Business endpoint.If you do not supply the BusinessId in the request, then the URL will be generated against the default business (First business created in your account).
    TINStringOptional Taxpayer Identification Number. Use this as an alternative for BusinessId or PayerRef.
Size Range: 9-11
Allowed values: "EIN", "SSN" (Including hyphen)
RecipientObjectCollects the recipient's unique identifier and other basic information of the recipient that will be pre-filled on the Form.
    PayeeRefStringAn unique identifier for each recipient completing the Form W-9. This identifier will be used in future references of the recipient in the API.
Size Range: 1-50
    NameStringOptional Recipient Name. This will be pre-filled on the Form.
Size Range: ..50
    AddressObjectCollects US address details of the recipient.
        Address1StringOptional Recipient US Address 1 (street address or post office box of that locality). This will be pre-filled on the Form.
Size Range: ..35
        Address2StringOptional Recipient US Address 2 (suite or apartment number). This will be pre-filled on the Form.
Size Range: ..35
        CityStringOptional Recipient US City. This will be pre-filled on the Form.
Size Range: ..27
        StatestringOptional Recipient US State Code. This will be pre-filled on the Form.
Size Range: 2
Allowed values: "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP"
        ZipCdStringOptional Recipient Zip Code. In the format 99999 or 99999-9999. This will be pre-filled on the Form.
Size Range: 5,9
    IsTINMatchingBooleanOptional TIN Matching will be enabled when the value is set as True. Once the recipient completes Form W-9, TaxBandits will match the Recipient's Name and SSN with the IRS database and notify the client via the webhook with the TIN results.
Allowed values: "true", "false"
    CustomizationObjectCollects the customizations like TIN service, Business Logo and Callback URLs.
        BusinessLogoUrlStringOptional Business Logo that will be displayed on the Form completion page.
Size Range: ..150
    RedirectUrlsObjectCollects the RedirectUrls like ReturnUrl and CancelUrl.
        ReturnUrlStringOptional Return Redirection URL. Set the callback URL redirection once the recipient completes filling the Form W-9.
Size Range: ..150
        CancelUrlStringOptional Cancel Redirection URL. Set the callback URL when the recipient clicks the cancel button on the Form W-9.
Note: If you do not provide the Cancel Callback Redirection URL, the cancel button will not be shown to the recipient.
Size Range: ..150

Note : You need to supply one of these values - TIN or TBS Business Id or PayerRef. If neither is supplied, the default Business will be assumed.

Response Body

FieldTypeDescription
SubmissionIdGuidUnique identifier of a submission.
PayeeRefStringUnique identifier of the recipient.
W9UrlStringURL that can be embedded on the client's website using Iframe or other means.
ErrorsobjectShows error information. This object will list the errors in the request parameters.

Request 1: Request W-9 URL using Payee Reference alone. The URL will be generated for the default business defined in the TaxBandits application for your account. First, make sure the Form W-9 Status Change webhook is configured.

{  "Recipient": {    "PayeeRef": "Pe464522"  }}

Response 1: Distinctive URL is generated for specific PayeeRef and BusinessID. The completed form will be saved against a provided BusinessID. On submission, Webhook payload status will include W9 and TIN Matching statuses if opted.

{    "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",    "PayeeRef": "Pe464522",        "W9Url": "https://esignw9.taxforall.com?uId=95d1bedb-f6b4-4300-9186-751719050020",    "Errors": null}

Request 2: Request W-9 URL using Payee Reference and BusinessId.

{  "Requester": {    "BusinessId": "2ec0fee8-6076-4305-95e7-873936ebd1cd"  },  "Recipient": {    "PayeeRef": "Pe464522"  }}

Response 2: A unique URL is generated for a specific Payee Reference and BusinessId. The completed form will be saved against a specific BusinessId and PayeeRef and the "Form W-9 Status Change" webhook payload will include the W-9 data.

{    "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",    "PayeeRef": "Pe464522",        "W9Url": "https://esignw9.taxforall.com?uId=95d1bedb-f6b4-4300-9186-751719050020",    "Errors": null}

Request 3: Request W-9 URL with Payee Reference and Recipient details.

{  "Requester": null,  "Recipient": {    "PayeeRef": "Pe123451234",    "Name": "John",    "Address": {      "Address1": "1751 Kinsey Rd",      "Address2": "Main St",      "City": "Dothan",      "State": "AL",      "ZipCd": "36303"    },    "IsTINMatching": true  },  "Customization": null,  "RedirectUrls": null}

Response 3: A unique URL is generated for a specific Payee Reference . The completed form will be saved against a specific BusinessId and the "Form W-9 Status Change" webhook payload will include the W-9 data.

{    "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",    "PayeeRef": "Pe464522",        "W9Url": "https://esignw9.taxforall.com?uId=95d1bedb-f6b4-4300-9186-751719050020",    "Errors": null}

Request 4: Request W-9 URL with Recipient Payer Reference, Payee Reference, Business Logo, Callback redirection URLs and TIN Matching service.

{  "Requester": {    "PayerRef": "B12345"  },  "Recipient": {    "PayeeRef": "123456",    "Name": "John",    "Address": {      "Address1": "1751 Kinsey Rd",      "Address2": "Main St",      "City": "Dothan",      "State": "AL",      "ZipCd": "36303"    },    "IsTINMatching": true  },  "Customization": {    "BusinessLogoUrl": "https://example.com"  },  "RedirectUrls": {    "ReturnUrl": "https://example.com",    "CancelUrl": "https://example.com"  }}

Response 4: A unique URL is generated for a specific Payee Reference and payer reference along with the respective company whitelabel . The completed form will be saved against a specific  Payee Reference and payer reference and the "Form W-9 Status Change" webhook payload will include the W-9 data.

{   "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",      "PayeeRef": "123456",   "Url": "https://esignw9.taxforall.com?uId=95d1bedb-f6b4-4300-9186-751719050020",   "Errors": null}