RequestByUrl
This is a payee-initiated method wherein the secure URL provided by the TaxBandits API will be embedded in the client’s software or portal, enabling the payees/vendors to start the W-8BEN completion process on their own.
To complete Form W-8BEN, TaxBandits will provide a secure URL that can be opened on its own or embedded as an Iframe into a web page or native app. To get this 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 for the future references of the payee) and a business identifier (Business Id or TIN).
If you have a portal for your vendors, you can use this method to embed a secure URL and collect the W-8BEN information during the vendor onboarding process. Each vendor who logs in will get a unique URL-embedded page to complete their W8-BEN.
How does this work?
-
Like any other TaxBandits API Endpoint, the first step is to call the notification to get the access token. This access token must be provided in the request header as the ‘Bearer‘ token. Refer to the OAuth 2.0 Authentication for more information on JWT authentication and integrating with subsequent requests.
-
The second step is to call the [POST] FormW8Ben/RequestByUrl endpoint with the following values:
- Access Token in the header (this will be provided 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 - The PayeeRef can be anything that uniquely identifies the payee/vendor, such as the vendor id, contractor number, a random number, or even the payee’s email address (This will be used for future references of the payee).
- Payee Name and Address (Optional) - The payee information will be pre-filled on the form when passed in the request.
- Business Identifier (Business ID or TIN) - This is used to identify and save the W-BEN 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 TaxBandits-generated Business ID. You can also define the ‘Default Business’ in the TaxBandits Application and skip sending the Business Identifier along with the request.See below for more examples
- DBA Reference (Optional) - If you have multiple DBA names for your business, you can provide the DBA name you want to use as the Requester Name on W-BEN forms.
- Customizations (Optional) - You can provide the following things in your request for customization.
- Business Logo - You can provide your business logo and its position.
- Color Theme - Specify the primary and secondary colors of the page.
- ShowDownloadPage - Choose whether or not to provide your recipients with the option to download their completed form.
- RedirectUrls - Set the URLs to which you want the recipients to be redirected once they complete/cancel the W-8BEN submission.
-
TaxBandits API will generate a unique URL and send the link in the response, which must then be embedded into your software or portal (or) shown by itself (Hosted Solution). Upon clicking this link, the payees will be provided with the W-8BEN Form with built-in validations. Also, there will be an electronic signature pad that allows the payees to sign electronically and submit the form.
-
Once the payee completes and signs the Form W-8BEN, you will be notified via Webhook. The Webhook payload will have the W-8BEN information, such as the name, address, and EIN/SSN, along with the link to download the completed Form W-8BEN.
Refer to the Form W-8BEN webhook to learn more about webhook setup and sample payload.
Web Messaging
Instead of webhook, you can choose to receive notifications via web messaging. For more information, click here.
POST FormW8Ben/RequestByUrl
Request Json
Field | Type | Description |
---|---|---|
Requester | Object | Collects the Requestor identifier i.e., 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 provide the BusinessId in the request, then the URL will be generated against the default business, i.e., the first business created in your account. |
DBAId | String | OptionalUnique Identifier for the DBA. |
DBARef | String | OptionalA Unique identifier for each DBA. This identifier can be used in future references for the DBA in the API. Size Range: 1 - 50 |
TIN | String | OptionalTaxpayer 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 | A unique identifier for each recipient completing the Form W-8BEN which will be used for future reference. Size Range: 1-50 |
Name | String | Optional Recipient Name. This will be pre-filled on the Form. Size Range: ..40 |
Address | Object | Collects Foreign address details of the recipient. |
Address1 | String | Recipient’s foreign address line 1 (street address or post office box of that locality). This will be pre-filled on the Form. Size Range: ..50 |
Address2 | String | OptionalRecipient’s foreign address line 2 (suite or apartment number). This will be pre-filled on the Form. Size Range: ..50 |
City | String | OptionalRecipient’s Foreign City Name. This will be pre-filled on the Form. Size Range: ..50 |
ProviceOrStateNm | String | Recipient’s Foreign State or Province Name. This will be pre-filled on the Form. Size Range: ..50 |
Country | String | Optional Recipient's country code. Refer to Static values. Size Range: 2 Allowed values"AF", "AX", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "AT", "AS", "AU", "AJ", "BF", "BA", "FQ", "BG", "BB", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "CA", "CV", "CJ", "CT", "CD", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "CS", "IV", "HR", "CU", "UC", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "EK", "ER", "EN", "ET", "FK", "FO", "FM", "FJ", "FI", "FR", "FP", "FS", "GB", "GA", "GG", "GM", "GH", "GI", "GR", "GL", "GJ", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "VT", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "KZ", "KE", "KQ", "KR", "KN", "KS", "KV", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MR", "MP", "MX", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "WA", "NR", "BQ", "NP", "NL", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "CQ", "NO", "MU", "OC", "PK", "PS", "LQ", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RO", "RS", "RW", "TB", "RN", "WS", "SM", "TP", "SA", "SG", "RI", "SE", "SL", "SN", "NN", "LO", "SI", "BP", "SO", "SF", "SX", "OD", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UK", "UY", "UZ", "NH", "VE", "VM", "VQ", "WQ", "WF", "WI", "YM", "ZA", "ZI" |
PostalCd | String | Recipient's postal code . Size Range: ..16 |
CustomizationId | Guid | Optional A unique customization identifier generated by TaxBandits after you complete the customization in the console. Note: You can customize the W-8BEN page (secure URL) with your own logo, fav icon, primary and secondary colors, and email. |
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 |
LogoPosition | String | Optional The position where your business logo will be placed on the page.Allowed values“LEFT”, “CENTER”, “RIGHT” |
InterviewFlow | Boolean | Optional If TRUE, your vendors will fill the W-8BEN in an interview flow instead of the traditional Form filling flow. |
PrimaryColor | String | Optional The color theme of the iframe page will be customized with this primary color. |
SecondaryColor | String | Optional The color theme of the iframe page will be customized with this secondary color. |
ShowDownloadPage | Boolean | Optional If TRUE, will provide an option for your payees to download their form |
RedirectUrls | Object | Collects the Redirect Urls as ReturnUrl and CancelUrl. |
ReturnUrl | String | Optional Return Redirection URL. Set the callback URL redirection once the recipient completes filling the Form W-8BEN. Size Range: ..150 |
CancelUrl | String | Optional Cancel Redirection URL. Set the callback URL when the recipient clicks the cancel button on the Form W-8BEN. Note: If you do not provide the Cancel Callback Redirection URL, the cancel button will not be shown to the recipient. Size Range: ..150 |
Request Json
- Sample 1
- Sample 2
- Sample 3
- Sample 4
- Sample 5
Request URL for Form W8-BEN with Payer Reference and opt for Customization
{
"Requester": {
"PayerRef": "B12345",
"BusinessId": null,
"TIN": null,
"DBAId": null,
"DBARef": null
},
"Recipient": {
"PayeeRef": "123456",
"Name": "John",
"Address": {
"Address1": "22 St",
"Address2": "Clair Ave E",
"City": "Toronto",
"ProvinceOrStateNm": "Ontario",
"Country": "CA",
"PostalCd": "M1R 0E9"
}
},
"Customization": {
"BusinessLogoUrl": "https://www.spanenterprises.com/Content/Images/span.png",
"LogoPosition": "CENTER",
"PrimaryColor": "FFFFFF",
"SecondaryColor": "222222",
"ShowDownloadPage": true
},
"RedirectUrls": {
"ReturnUrl": "https://exampleweblink1.com",
"CancelUrl": "https://exampleweblink2.com"
}
}
Request URL with Payee Reference and Recipient details. The Recipient Address will be pre-filled in the form No Requester details were sent.
{
"Requester": {
"PayerRef": null,
"BusinessId": null,
"TIN": null,
"DBAId": "97a16024-c7d2-41d7-92fe-103341d58fa0",
"DBARef": "24BC"
},
"Recipient": {
"PayeeRef": "123456",
"Name": "John",
"Address": {
"Address1": "22 St",
"Address2": "Clair Ave E",
"City": "Toronto",
"ProvinceOrStateNm": "Ontario",
"Country": "CA",
"PostalCd": "M1R 0E9"
}
},
"Customization": null,
"RedirectUrls": null
}
Request URL for Form W-8BEN/W-8 with BusinessId and RecipientId and provided RedirectUrl.
{
"Requester": {
"PayerRef": null,
"BusinessId": "619945fa-aab8-40e3-b518-94d774d9ccf6",
"TIN": null,
"DBAId": null,
"DBARef": null
},
"Recipient": {
"PayeeRef": "123456",
"Name": "John",
"Address": {
"Address1": "22 St",
"Address2": "Clair Ave E",
"City": "Toronto",
"ProvinceOrStateNm": "Ontario",
"Country": "CA",
"PostalCd": "M1R 0E9"
}
},
"Customization": null,
"RedirectUrls": {
"ReturnUrl": "https://exampleweblink1.com",
"CancelUrl": "https://exampleweblink2.com"
}
Request URL with Payee Reference and Recipient details. No Requester details were sent in and customization with the redirection url.
{
"Requester": {
"PayerRef": null,
"BusinessId": null,
"TIN": null,
"DBAId": null,
"DBARef": null
},
"Recipient": {
"PayeeRef": "123456",
"Name": "John",
"Address": {
"Address1": "22 St",
"Address2": "Clair Ave E",
"City": "Toronto",
"ProvinceOrStateNm": "Ontario",
"Country": "CA",
"PostalCd": "M1R 0E9"
}
},
"Customization": {
"BusinessLogoUrl": "https://www.spanenterprises.com/Content/Images/span.png",
"LogoPosition": "CENTER",
"InterviewFlow": true,
"PrimaryColor": "#CC0066",
"SecondaryColor": "#FF99CC",
"ShowDownloadPage": true
},
"RedirectUrls": {
"ReturnUrl": "https://exampleweblink1.com",
"CancelUrl": "https://exampleweblink2.com"
}
}
Create a customized Form W-8BEN secure URL based on the CustomizationId.
{
"Requester": {
"PayerRef": null,
"BusinessId": "011d9058-fc7c-4182-bb4e-68d5ed7d7b2c",
"TIN": null,
"DBAId": null,
"DBARef": null
},
"Recipient": {
"PayeeRef": "123456",
"Name": "John",
"Address": {
"Address1": "22 St",
"Address2": "Clair Ave E",
"City": "Toronto",
"ProvinceOrStateNm": "Ontario",
"Country": "CA",
"PostalCd": "M1R 0E9"
}
},
"CustomizationId": "0ecbdb4f-4cf0-440f-b412-8793eeaf6ee1",
"Customization": null,
"RedirectUrls": {
"ReturnUrl": "https://exampleweblink1.com",
"CancelUrl": "https://exampleweblink2.com"
}
}
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
- Response 2
- Response 3
- Response 4
- Response 5
{
"SubmissionId": "3adc8b08-8d3d-4f76-8244-a871c81d72e1",
"PayeeRef": "123456",
"W8BenUrl": "https://testlinks.taxbandits.io?uId=2082121e-7614-4901-b0c3-9dce37224b40",
"Errors": null
}
{
"SubmissionId": "3adc8b08-8d3d-4f76-8244-a871c81d72e1",
"PayeeRef": "123456",
"W8BenUrl": "https://testlinks.taxbandits.io?uId=2082121e-7614-4901-b0c3-9dce37224b40",
"Errors": null
}
{
"SubmissionId": "3adc8b08-8d3d-4f76-8244-a871c81d72e1",
"PayeeRef": "123456",
"W8BenUrl": "https://testlinks.taxbandits.io?uId=2082121e-7614-4901-b0c3-9dce37224b40",
"Errors": null
}
{
"SubmissionId": "3adc8b08-8d3d-4f76-8244-a871c81d72e1",
"PayeeRef": "123456",
"W8BenUrl": "https://testlinks.taxbandits.io?uId=2082121e-7614-4901-b0c3-9dce37224b40",
"Errors": null
}
{
"SubmissionId": "27517d44-41d3-44d4-9eba-40de11032e84",
"PayeeRef": "123456",
"W8BenUrl": "https://testlinks.taxbandits.io?uId=a9e10bc7-00ec-4586-9b4a-cceab87b39aa",
"Errors": null
}
The default business details will be considered as the requester's details.