RequestByUrl

TaxBandits will supply the W-8BEN URL uniquely for each request. 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, 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 response returns a unique URL that may be opened on its own or embedded within an Iframe into a web page or native app. Recommended when you have a portal for your vendors, where you can place a link to collect the W8BEN information. Option to customize logo and the callback redirection URLs are available.

How does this work?

1. Call the [GET] FormW8Ben/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 as Bearer Token (generated using TaxBandits OAuth authentication API).
   • Payee Reference (unique information that identifies the Recipient). Can be the Vendor id, contractor number, recipient email address, or a random number. Will be used to identify the recipient for future references.
   • PayerRef (Optional), Business Id (Business Identifier) or TIN - To identify and save the W9/W-8BEN under a particular Business. Refer to the Business endpoint to learn more about creating a Business in TaxBandits. If you don’t supply one in the request, it will be associated with the default business (first business created in your account).
   • Recipient Name and Address (optional) - The recipient information will be pre-filled on the form when passed in the request.
   • Business Logo and Callback URLs (optional) - Customize the business logo on the Form Form W8-BEN. Set callback redirection URLs upon submission or cancelation. 

2. 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-8BEN with built-in validations. An electronic signature pad that allows the recipient to sign electronically and submit the form is available.

3. Once the recipient completes and signs the form, you will be notified via webhook. The webhook payload will have the recipient data such as Name, Citizenship country, address, and reduced tax rate for W-8BEN.

Refer to the Form W-8BEN webhook to know more about webhook set up and sample payload.

GET FormW8Ben/RequestByUrl 

Request Params

Field	Type	Description
PayeeRef	String	A unique identifier for each recipient completing the Form W-8BEN. This identifier will be used in future references of the recipient in the API 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 using the default business (First business created in your account).
TIN	String	Optional Taxpayer Identification Number. Use this as an alternative for BusinessId. Values: EIN, SSN Note : You need to supply one of these values - TIN or TBS Business Id. If neither is supplied, the default Business will be assumed. Size Range: 9-11(Including hyphen)

Request Params

Sample 1

Request W-8BEN URL using Payee Reference and BusinessId. Make sure to configure the W-8BEN Webhook console.

FormW8Ben/RequestByUrl?PayeeRef=Pe464522&BusinessId=314ddb71-a6ac-4312-ab09-7ad9a2b3507d

Sample 2

Request W-8BEN URL using Payee Reference and TIN.

FormW8Ben/RequestByUrl?PayeeRef=Pe464522&TIN=123456789

Sample 3

Request W-8BEN URL using Payee Reference.

FormW8Ben/RequestByUrl?PayeeRef=Pe464522

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
PayeeRef	String	Unique identifier of the recipient.
W8BenUrl	String	URL that can be accessed on its own or embedded on the client's website using Iframe or other means.
Errors	object[]	Collection of errors for the Recipient
Id	string	Error ID number. This ID is assigned by TaxBandits and it is unique for each error.
Name	string	Name of the errored node.
Message	string	Shows the error message

Response JSON

Response 1

Distinctive URL is generated for specific PayeeRef and Business ID. The completed Form W-8BEN will save against a specific business. When a recipient submits the form, the "Form W-8BEN Status Change" webhook payload will include the W-8BEN data.

{
 "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
 "PayeeRef":"Pe464522",  
 "W8BenUrl":"https://testlinks.taxbandits.io?uId=ebebc7d1-0553-4a19-9d5a-4f97b37e56f8",
 "Errors":null
}

Response 2

A unique URL is generated for specific PayeeRef and TIN. The completed form will be saved against a specific Business TIN. When a recipient submits the form, the "Form W-8BEN Status Change" webhook payload will include the W-8BEN data.

{
 "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
 "PayeeRef":"Pe464522", 
 "W8BenUrl":"https://testlinks.taxbandits.io?uId=ebebc7d1-0553-4a19-9d5a-4f97b37e56f8",
 "Errors":null
}

Response 3

A unique URL will be generated for specific PayeeRef. Since the business id is not specified, the completed Form W-8BEN will save against a default Business."  When a recipient submits the form, the "Form W-8BEN Status Change" webhook payload will include the W-8BEN data.

{
 "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
 "PayeeRef":"Pe464522", 
 "W8BenUrl":"https://testlinks.taxbandits.io?uId=ebebc7d1-0553-4a19-9d5a-4f97b37e56f8",
 "Errors":null
}