RequestByUrl

To complete the Form W-8BEN, TaxBandits will supply the URL that can be opened on its own or embedded as an Iframe 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, 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 where you can place a link to collect the W8BEN information. Each vendor who logs in will get a unique url embedded page to complete their W8BEN.

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 the 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 FormW8Ben/RequestByURL API endpoint. If you are trying to 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 as Bearer Token (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) - This is used to identify and save the W8BEN 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. More information and examples of this are outlined below.

3. TaxBandits will generate a 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-8BEN 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-8BEN, you will be notified via webhook. The webhook payload will have the W-8BEN recipient data such as the Name, Address and TIN(US/Foreign) along with the link to download the completed Form W-8BEN.
   

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

GET FormW8Ben/RequestByUrl

Request Body

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)

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

Request 1 : Request W-8BEN URL using Payee Reference and BusinessId.

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

Response 1

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

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

FormW8Ben/RequestByUrl?PayeeRef=Pe464522&TIN=123456789

Response 2

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

Request 3 : Request W-8BEN URL using Payee Reference.

FormW8Ben/RequestByUrl?PayeeRef=Pe464522

Response 3

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