Skip to main content
Version: 1.7.3

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?

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

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

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

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

note

Web Messaging

Instead of webhook, you can choose to receive notifications via web messaging. For more information, click here.

POST FormW8Ben/RequestByUrl
Run in Postman

Request Json

FieldTypeDescription
RequesterObjectCollects 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.
PayerRefStringOptional Unique payer identifier assigned by the client while requesting the payer information using the endpoint Business/RequestByURL.
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 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.
DBAIdStringOptionalUnique Identifier for the DBA.
DBARefStringOptionalA Unique identifier for each DBA. This identifier can be used in future references for the DBA in the API.
Size Range: 1 - 50
TINStringOptionalTaxpayer Identification Number. Use this as an alternative for BusinessId or PayerRef.
Size Range: 9-11
Allowed values : "EIN" , "SSN" (Including hyphen)
RecipientObjectCollects the recipient's unique identifier and other basic information of the recipient that will be pre-filled on the Form.
PayeeRefStringA unique identifier for each recipient completing the Form W-8BEN which will be used for future reference.
Size Range: 1-50
NameStringOptional Recipient Name. This will be pre-filled on the Form.
Size Range: ..40
AddressObjectCollects Foreign address details of the recipient.
Address1StringRecipient’s foreign address line 1 (street address or post office box of that locality). This will be pre-filled on the Form.
Size Range: ..35
Address2StringOptionalRecipient’s foreign address line 2 (suite or apartment number). This will be pre-filled on the Form.
Size Range: ..35
CityStringOptionalRecipient’s Foreign City Name. This will be pre-filled on the Form.
Size Range: ..27
ProviceOrStateNmStringRecipient’s Foreign State or Province Name. This will be pre-filled on the Form.
Size Range: ..30
CountryStringOptional Recipient's country code. Refer to Static values.
Size Range: 2
Allowed values

"CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"

PostalCdStringRecipient's postal code
CustomizationObjectCollects the customizations like TIN service, Business Logo and Callback URLs.
BusinessLogoUrlStringOptional Business Logo that will be displayed on the Form completion page.
Size Range: ..150
LogoPositionStringOptional The position where your business logo will be placed on the page.
Allowed values

“LEFT”, “CENTER”, “RIGHT”

PrimaryColorStringOptional The color theme of the iframe page will be customized with this primary color.
SecondaryColorStringOptional The color theme of the iframe page will be customized with this secondary color.
ShowDownloadPageBooleanOptional If TRUE, will provide an option for your payees to download their form
RedirectUrlsObjectCollects the Redirect Urls as ReturnUrl and CancelUrl.
ReturnUrlStringOptional Return Redirection URL. Set the callback URL redirection once the recipient completes filling the Form W-8BEN.
Size Range: ..150
CancelUrlStringOptional 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

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"
    }
}

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

Response JSON

{
    "SubmissionId": "3adc8b08-8d3d-4f76-8244-a871c81d72e1",
    "PayeeRef": "123456",
    "W8BenUrl": "https://testlinks.taxbandits.io?uId=2082121e-7614-4901-b0c3-9dce37224b40",
    "Errors": null
}
note

The default business details will be considered as the requester's details.