Skip to main content
Version: 1.7.3

RequestByUrl

RequestByUrl

This is a payee-initiated method that allows vendors, contractors, or affiliates to complete Form W-9 or W-8 on their own, using a secure URL generated by the TaxBandits API. You can embed this URL into your application/portal as an iframe.

How it works​

1. OAuth 2.0 Authentication​

As with any TaxBandits API call, begin by authenticating through the OAuth 2.0 flow to obtain an access token. This token must be included in the request header as a Bearer token. Refer to the OAuth 2.0 Authentication guide for details on JWT authentication and token handling.

2. Create Business​

Before initiating a W-9/W-8 request, ensure at least one business (payer) has been created using the Business endpoint. This is a mandatory step.

3. Call the [POST] WhCertificate/RequestByUrl endpoint​

Your request must include the following:

  • Authorization Header - Include the Bearer token obtained from OAuth.
  • Payee Reference (Optional) - A unique identifier for the payee (e.g., vendor ID, email, or random ID). This will be used for future references to this recipient.
  • Payee Name and Address (Optional) - Pre-fills the form with payee details.
  • Business Identifier (Optional) - Provide the BusinessId or TIN to identify the payer associated with the request. If omitted, the form will be tied to the first business in your account.
  • DBA Reference (Optional) - Used to display a specific DBA name as the requester on the form.
  • Customizations (Optional) - You may include branding customization in the request, such as logo, theme colors, etc, and the redirection URLs where you want the payee to be redirected once they submit the form. You may also include a CustomizationId if you’ve generated one. Learn more
  • Languages (Optional) – Specify the language for the form. Recipients can also change their preferred language if needed. Supported languages: English, French, Spanish, German, Ukrainian and Portuguese

4. Payee completes the form​

Once your request is submitted, TaxBandits will return a secure URL in the response. You can either:

  • Embed this URL in your application or portal
  • Share the link directly with the respective payee

Upon clicking the secure URL, the payee will be provided with the option to choose the Form W-9, W-8BEN, W-8BEN-E, or W-8ECI based on their citizenship and resident status. They can complete, e-sign, and submit the form.

5. Get notified​

  • Webhooks - If you’ve configured Webhooks for the event type 'WhCertificate Status Change Webhook', you will receive a webhook notification once the payee submits the form. The Webhook payload includes payee details (name, TIN, address) and a link to download the completed form. Learn more
  • Status endpoint - Alternatively, you can also use the Status endpoint to retrieve the status.
  • Web messaging - Instead of Webhooks, you can choose to receive notifications via web messaging. For more information, click here.
Automate TIN Matching


If you want to validate the TINs automatically once collected, you can set the IsTINMatching as TRUE in your request JSON.

POST WhCertificate/RequestByUrl
Run in Postman

Request Body

FieldTypeDescription
RequesterObjectCollects the Requestor identifier i.e., TIN or TaxBandits 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.
    TINStringOptionalTaxpayer Identification Number. Use this as an alternative for BusinessId or PayerRef.
Size Range: 9-11
    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
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-9 which will be used for future reference.
Size Range: 1-50
    FedTaxClassStringOptional Federal tax classification of the recipient. This will be pre-filled on the Form.
Allowed values

"INDIVIDUAL", "SOLE_PROPRIETOR", "C_CORPORATION", "S_CORPORATION", "PARTNERSHIP", "TRUST_ESTATE", "SINGLE_MEMBER_LLC_ELECTED", "SINGLE_MEMBER_LLC_NOT_ELECTED", "LLC_C_CORPORATION", "LLC_S_CORPORATION", "LLC_P_CORPORATION"

    EmailStringEmail address of the recipient
Size Range: ..100
    NameStringOptional Recipient Name. This will be pre-filled on the Form.
Size Range: ..40
    IsForeignBooleanWhen true, identify the recipient address with a foreign address.
    USAddressObjectOptional Collects US address details of the recipient.
        Address1StringOptionalRecipient US Address 1 (street address or post office box of that locality). This will be pre-filled on the Form.
Size Range: ..46
        Address2StringOptionalRecipient US Address 2 (suite or apartment number). This will be pre-filled on the Form.
Size Range: ..46
        CityStringOptionalRecipient US City. This will be pre-filled on the Form.
Size Range: ..50
        StateStringOptionalRecipient US State Code. This will be pre-filled on the Form.
Size Range: 2
Allowed values

"AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP"

        ZipCdStringOptionalRecipient Zip Code. In the format 99999 or 99999-9999. This will be pre-filled on the Form.
Size Range: 5..10
    ForeignAddressObjectOptional If IsForeign is true, pass foreign address of the recipient
        Address1StringOptionalRecipient's foreign address (street address or post office box of that locality)
Size Range: ..50
        Address2StringOptionalRecipient's suite or apartment
Size Range: ..50
        CityStringOptional Recipient's city.
Size Range: ..50
        ProvinceOrStateNmStringOptionalRecipient's Province or State Name.
Size Range: ..50
        CountryStringOptionalRecipient's country code.
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"

        PostalCdStringOptionalRecipient's Postal Code.
Size Range: ..16
    IsTINMatchingBooleanOptional TIN Matching will be enabled when the value is set as True. Once the recipient completes Form W-9, TaxBandits will match the Recipient's Name and SSN with the IRS database and notify the client via the webhook with the TIN results.
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: Redirect URL is measured in seconds.
CustomizationObjectCollects the customizations like TIN service, Business Logo and Callback URLs.
    BusinessLogoUrlStringOptional Gets the Business Logo. If given the business logo will be shown in the Iframe page.
Size Range: ..150
    LogoPositionStringOptional The position where your business logo will be placed on the page.
Allowed values

“LEFT”, “CENTER”, “RIGHT”

    InterviewFlowBooleanOptional As an alternative to direct-form entry, provide your recipients with an interview-style W-9/W-8 completion.
    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.
    PrefLangStringOptionalGets the default display language for the portal. If not set, English will be shown.
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.
UrlStringURL 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
Note:

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

Request Json​

Request the URL for Form W-9/W-8 with PayerRef, PayeeRef, and the provided Redirect URL.

{
  "Requester": {
      "PayerRef": "B12345",
      "BusinessId": null,
      "TIN": null,
      "DBAId": null,
      "DBARef": null
  },
  "Recipient": {
      "PayeeRef": "123456",
      "Name": "John",
      "IsTINMatching": true,
      "FedTaxClass":"INDIVIDUAL",
      "Email":"john@sample.com"
  },
  "Customization": {
      "BusinessLogoUrl": "https://www.spanenterprises.com/Content/Images/span.png",
      "LogoPosition": "CENTER",
      "InterviewFlow": true,
      "PrimaryColor": "#1be6f5",
      "SecondaryColor": "#9c9276",
      "ShowDownloadPage": true,
      "PrefLang": "es-ES"
  },
  "RedirectUrls": {
      "ReturnUrl": "https://example.com",
      "CancelUrl": "https://example.com"
  },
  "WebhookRef": "0D14C79F-5FD6-4983-9809-023F0C2BF817",
}

Response JSON​

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

{
  "SubmissionId": "7971f12e-fc8f-4d88-91c9-deb4696d3612",
  "PayeeRef": "123456",
  "Url": "https://testlinks.taxbandits.io?whId=7b20d2c0-6585-435c-89c7-3a01b13d33ef",
  "Errors": null
}