Skip to main content
Version: 1.7.3

RequestByUrl

RequestByUrl

This is a payee-initiated method where the API generates a unique secure URL per recipient. You can share the URL directly with recipients or embed it in your platform as an iframe, and recipients can complete the form on their own.

When to use​

  • You want recipients to access and complete the form on their own, without sending a direct email or SMS invitation.
  • You want to embed the form completion experience directly into your platform as an iframe, keeping recipients within your application.

If you want a single shared URL for all recipients under a payer, use RequestByBusinessUrl instead.

How it works​

  1. Authenticate

    Obtain a Bearer token via the OAuth 2.0 flow and include it in all request headers.

  2. Ensure a business (payer) exists

    Before calling this endpoint, confirm the payer has been created using the Business endpoint. If no BusinessId is provided in the request, the request will be associated with the default payer (the first payer created in your account).

  3. Call the endpoint

    Along with the payer and recipient details, your request may include the following optional parameters:

    • DBAId / DBARef — Scope the URL to a specific DBA under the payer. The DBA name will appear as the requester on the form.
    • Customization — Apply your logo and primary/secondary colors to brand the form page. Alternatively, pass a CustomizationId generated from the PortalCustomization endpoint.
    • InterviewFlow — Set to TRUE to present the W-8BEN as a guided interview rather than a traditional form.
    • ShowDownloadPage — Set to TRUE to give recipients the option to download their completed form.
    • PrefLang — Specify the language for the form. Recipients can also change their preferred language if needed. Supported languages: English, French, Spanish, German, Ukrainian, and Portuguese.
    Automate TIN Matching

    Set IsTINMatching to TRUE to automatically trigger IRS TIN Matching once the recipient submits their form.

  4. Recipient completes the form

    The API returns a Url in the response — a unique, recipient-specific secure URL. You can:

    • Embed it in your application or portal as an iframe.
    • Share it directly with the recipient via your own email, SMS, or messaging system.

    When the recipient opens the link, they select the applicable Form W-8BEN and complete, e-sign, and submit it.

  5. Get notified

    Once a recipient submits, you can receive notification through any of the following:

    • Webhooks — Configure the 'Form W-8BEN Status Change' webhook event to receive a payload with the recipient's name, TIN, address, and a link to download the completed form. Learn more
    • Status endpoint — Poll the Status endpoint on demand to retrieve the current form status for a given recipient.
    • Web messaging — Receive in-browser notifications when a recipient completes their form. Learn more
POST FormW8Ben/RequestByUrl
Run in Postman

Request Body

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
W8TaxBenefitsObjectObject that contains information about tax treaty benefits of the recipient
BeneficiaryCountryStringCountry where the recipient claim to be a resident for income tax treaty purposes.
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"

ClaimingProvArticleParaStringArticle and paragraph of the treaty benefits.
Size Range: 25
RateOfWHStringRate of withholding.
Size Range: ..100
TypeOfIncomeStringType of income for which the recipient claims the treaty benefits.
Allowed values

"PAID_BY_US_OBLIGORS_GENERAL", "PAID_BY_US_CORPORATIONS","QUALIFYING_FOR_DIRECT_DIVIDEND_RATE","PENSIONS_AND_ANNUITIES", "SOCIAL_SECURITY", "INDUSTRIAL_EQUIPMENT", "KNOW_HOW_OTHER_INDUSTRIAL_ROYALTIES", "PATENTS", "FILM_AND_TV", "COPYRIGHTS"

AdditionalConditionsStringAdditional conditions from the tax treaty benefits.
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: ..50
Address2StringOptionalRecipient’s foreign address line 2 (suite or apartment number). This will be pre-filled on the Form.
Size Range: ..50
CityStringOptionalRecipient’s Foreign City Name. This will be pre-filled on the Form.
Size Range: ..50
ProviceOrStateNmStringRecipient’s Foreign State or Province Name. This will be pre-filled on the Form.
Size Range: ..50
CountryStringOptional 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"

PostalCdStringRecipient's postal code .
Size Range: ..16
WebhookRefGuidOptional A unique identifier of the Webhooks that TaxBandits generates against each Callback URL when adding it to the console site.
If you pass the WebhookRef in the request JSON, we will post the webhook response to the corresponding Callback URL. If you don't pass one, the webhook response will be posted to the default Callback URL.
CustomizationIdGuidOptional A unique customization identifier generated by TaxBandits after you complete the customization process in the Developer console or the unique ID you received in the response of the PortalCustomization CREATE Endpoint. endpoint.
Note: You can customize the W-9/W-8 page (secure URL) with your own logo, favicon, and primary and secondary colors.
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”

InterviewFlowBooleanOptional If TRUE, your vendors will fill the W-8BEN in an interview flow instead of the traditional Form filling flow.
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
PrefLangStringOptionalLanguage Preference of the form
Allowed values

"en-US", "es-ES", "fr-FR","de-DE","uk-UA","pt-PT"

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
RedirectTimeNumberOptional Redirection Time. Set the time before redirecting to the callback URL.
Note: Redirect URL is measured in seconds.
Size Range:5-300

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

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

Request Json​

Request URL with Payee Reference, Recipient details and Customization with redirectionurl

{
  "Requester": {
      "PayerRef": null,
      "BusinessId": null,
      "TIN": null,
      "DBAId": null,
      "DBARef": null
  },
  "Recipient": {
      "PayeeRef": "123456",
      "Name": "John",
      "W8TaxBenefits": {
          "BeneficiaryCountry": "ZA",
          "ClaimingProvArticlePara": "Article 12(4)",
          "RateOfWH": "10.0",
          "TypeOfIncome": "SOCIAL_SECURITY",
          "AdditionalConditions": "Interest on debt -- India treaty    reduced"
      },
      "Address": {
          "Address1": "22 St",
          "Address2": "Clair Ave E",
          "City": "Toronto",
          "ProvinceOrStateNm": "Ontario",
          "Country": "CA",
          "PostalCd": "M1R 0E9"
      }
  },
  "WebhookRef":"2E9C7CA0-F0CF-4257-99AA-7FD6CCFD9D4",
  "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",
      "RedirectTime": 60
  }
}

Response JSON​

Success Response - This is a sample response for successful API requests.

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