Skip to main content
Version: 1.6.1

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.

  1. 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.
  2. 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.

  3. 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

FieldTypeDescription
PayeeRefStringA 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
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 using the default business (First business created in your account).
TINStringOptional 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

FieldTypeDescription
SubmissionIdGuidUnique identifier of a submission.
PayeeRefStringUnique identifier of the recipient.
W8BenUrlStringURL that can be accessed on its own or embedded on the client's website using Iframe or other means.
        Errorsobject[]Collection of errors for the Recipient
            IdstringError ID number. This ID is assigned by TaxBandits and it is unique for each error.
            NamestringName of the errored node.
            MessagestringShows 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}