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-9 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-9 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-9 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 FormW9/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
    IsForeignBooleanOptional Set to TRUE if the recipient has a foreign address. When TRUE, pass address details under ForeignAddress instead of USAddress.
    AddressObjectCollects US address details of the recipient.
        Address1StringOptional Recipient US Address 1 (street address or post office box of that locality). This will be pre-filled on the Form.
Size Range: ..46
        Address2StringOptional Recipient 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 Recipient's foreign address. Required when IsForeign is TRUE.
        Address1StringOptional Street address or PO Box.
Size: 1–50
        Address2StringOptional Suite or apartment number.
Size: 1–50
        CityStringOptional City.
Size: 1–50
        ProvinceOrStateNmStringOptional Province or state name.
Size: 1–50
When the country code is CA
Allowed values

"Alberta", "British Columbia", "Manitoba", "New Brunswick", "Newfoundland and Labrador", "Northwest Territories", "Nova Scotia", "Nunavut", "Ontario", "Prince Edward Island", "Quebec", "Saskatchewan", "Yukon Territory"

        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"

        PostalCdStringOptional Postal code.
Size: 1–16
    IsTINMatchingBooleanOptionalTIN 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.
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.
CustomizationObjectOptionalCollects 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 Gets the position in which the logo should be displayed.
Allowed values

“LEFT”, “CENTER”, “RIGHT”

    InterviewFlowBooleanOptional If TRUE, your vendors will fill the W-9 in an interview flow instead of the traditional Form filling flow.
    PrimaryColorStringOptional Gets the primary color for the portal. You can use this to customize the color theme of the portal to match with your application color
    SecondaryColorStringOptional Gets the secondary color for the portal. You can use this to customize the color theme of the portal to match with your application color
    RedirectUrlsObjectCollects the Redirect Urls as ReturnUrl and CancelUrl.
    PrefLangStringOptionalLanguage Preference of the form
Allowed values

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

    ShowDownloadPageBooleanOptional If TRUE, your vendors will have the option to download the completed W-9 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-9.
Size Range: ..150
    CancelUrlStringOptional Cancel Redirection URL. Set the callback URL when the recipient clicks the cancel button on the Form W-9. 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.
W9UrlStringURL 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 Json​

Request URL with DBAId and DBARef details. The Recipient Address will be pre-filled in the form No Requester details were sent in and opted for TIN Matching.

{
"Requester": {
        "PayerRef": "NGD123",
        "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
        "TIN": "20-1652371",
        "DBAId": "97a16024-c7d2-41d7-92fe-103341d58fa0",
        "DBARef": "DBA NGD123"
 },
"Recipient": {
    "PayeeRef": "SG7356",
    "FedTaxClass": "INDIVIDUAL",
    "Name": "David Smith",
    "IsForeign": false,
    "Address": {
        "Address1": "1751 Kinsey Rd",
        "Address2": "Main St",
        "City": "Dothan",
        "State": "AL",
        "ZipCd": "36303"
    },
    "ForeignAddress": {
        "Address1": "120 Bremner Blvd",
        "Address2": "Suite 800",
        "City": "Toronto",
        "ProvinceOrStateNm": "Ontario",
        "Country": "CA",
        "PostalCd": "4168682600"
    },
    "IsTINMatching": true
},
"WebhookRef": "2E9C7CA0-F0CF-4257-99AA-7FD6CCFD9D4",
"Customization":null,
"RedirectUrls":null
}

Response JSON​

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

{
  "SubmissionId": "6e3195f2-4a56-4349-bb19-69d5f1bb5393",
  "PayeeRef": "123456",
  "W9Url": "https://testlinks.taxbandits.io?uId=6ccae518-e6f8-4c1c-83d9-767bb9949a02",
  "Errors": null
}