Version: 1.7.3

RequestByUrl

To complete the Form W-9, TaxBandits will supply the URL that can be opened on its own or embedded as an Iframe into a web page or native apps. 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?

Call the [POST] FormW9/RequestByUrl endpoint. If you are trying to embed this link into your web page, this endpoint must be called before you load the page. Supply the following parameters:

Access Token in the header (Will be supplied by TaxBandits or generated using TaxBandits OAuth authentication API) - Refer to OAuth 2.0 Authentication for more information on JWT authentication and how to integrate with the subsequent requests.
Payee Reference (Unique information that identifies the Recipient) - The PayeeRef 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) - 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 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.

TaxBandits API will generate a unique URL and send the link in the response, which must then be embedded into the page or shown by itself (Hosted Solution) for the recipients to click. When clicked, the recipient will be provided with the form W-9 with built-in validations. An electronic signature pad that allows the recipient to sign electronically and submit the form is available.
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

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

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.

POST FormW9/RequestByUrl

Request Body

Field	Type	Description
Requester	Object	Collects the Requestor identifier. TIN or TBS Business Id or PayerRef. If neither is supplied, the default Business will be assumed as the Requester.
PayerRef	String	`Optional` Unique payer identifier assigned by the client while requesting the payer information using the endpoint Business/RequestByURL. Size Range: 1-50
BusinessId	Guid	`Optional` 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).
TIN	String	`Optional` Taxpayer Identification Number. Use this as an alternative for BusinessId or PayerRef. Size Range: 9-11 Allowed values: "EIN", "SSN" (Including hyphen)
Recipient	Object	Collects the recipient's unique identifier and other basic information of the recipient that will be pre-filled on the Form.
PayeeRef	String	An 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
Name	String	`Optional` Recipient Name. This will be pre-filled on the Form. Size Range: ..50
Address	Object	Collects US address details of the recipient.
Address1	String	`Optional` Recipient US Address 1 (street address or post office box of that locality). This will be pre-filled on the Form. Size Range: ..35
Address2	String	`Optional` Recipient US Address 2 (suite or apartment number). This will be pre-filled on the Form. Size Range: ..35
City	String	`Optional` Recipient US City. This will be pre-filled on the Form. Size Range: ..27
State	string	`Optional` 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"
ZipCd	String	`Optional` Recipient Zip Code. In the format 99999 or 99999-9999. This will be pre-filled on the Form. Size Range: 5,9
IsTINMatching	Boolean	`Optional` 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"
Customization	Object	Collects the customizations like TIN service, Business Logo and Callback URLs.
BusinessLogoUrl	String	`Optional` Business Logo that will be displayed on the Form completion page. Size Range: ..150
RedirectUrls	Object	Collects the RedirectUrls like ReturnUrl and CancelUrl.
ReturnUrl	String	`Optional` Return Redirection URL. Set the callback URL redirection once the recipient completes filling the Form W-9. Size Range: ..150
CancelUrl	String	`Optional` 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

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
PayeeRef	String	Unique identifier of the recipient.
W9Url	String	URL that can be embedded on the client's website using Iframe or other means.
Errors	object	Shows 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://testlinks.taxbandits.io?uId=230871f3-4cc9-4848-9f79-2f6964eaca27",
    "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://testlinks.taxbandits.io?uId=230871f3-4cc9-4848-9f79-2f6964eaca27",
    "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://testlinks.taxbandits.io?uId=230871f3-4cc9-4848-9f79-2f6964eaca27",
    "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://www.spanenterprises.com/Content/Images/span.png"
  },
  "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://testlinks.taxbandits.io?uId=230871f3-4cc9-4848-9f79-2f6964eaca27",
   "Errors": null
}

Extend your software with TaxBandits IRS E-file API Integration