Skip to main content
Version: 1.7.0

RequestByUrl

This is a payee-initiated method wherein the secure URL provided by the TaxBandits API will be embedded as an iframe in the client’s software or portal, enabling the payees/vendors to start the W-9/W-8 completion process on their own.

To complete Form W-9/W-8, 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-9 information during the vendor onboarding process. Each vendor who signs in will get a unique URL-embedded page to complete their W9.

How does this work?

  1. Call the [POST] WhCertificate/RequestByUrl endpoint. If you are trying to embed this link into your web page, this endpoint must be called before you load the page.

    Provide the following parameters:

    • Access Token in the header as Bearer Token (generated using TaxBandits OAuth authentication API).
    • 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.
    • PayerRef, Business Id (Business Identifier) or TIN - - This will be used to identify and save the W9/W-8BEN under a particular Business. Refer to the Business endpoint to learn more about creating a Business in TaxBandits. If you don’t provide one in the request, it will be associated with the default business (the first business created in your account).
    • Recipient Name and Address (optional) -When passed in the request, will be pre-filled on the form the recipient fills.
    • Customization of Business Logo and Callback URLs (optional) - You can customize the business logo on the Form W-9/Form W8-BEN completion page. Also, you can customize the callback redirection URLs upon submission or cancellation.
    • WebhookRef (optional) - Pass the Webhook Reference ID, and we will post the Webhook response to the corresponding Callback URL. If you do not specify one, the Webhook will be posted to the default Webhook URL.

  2. TaxBandits API will generate a unique URL and send the link in the response, which must then be embedded into the page or shown by itself (Hosted Solution) for the recipients to click. Upon clicking, the recipient will be provided with the option to choose the Form W-9 or W-8BEN based on their citizenship and resident status. Accordingly, Form W-9, or W-8BEN will be shown with built-in validations. An electronic signature pad allows the recipient to sign electronically and submit the form.

  3. Once the recipient completes and signs the form, you will be notified via Webhooks. If the node WebhookRef in the request JSON has a Webhook Reference ID, the Webhook response will be posted to the corresponding Callback URL.

The webhook payload will have the following recipient data:

  • For W-9 - Name, address, email, TIN Matching status, form data, PDFURL to download the completed form, etc.
  • For W-8BEN - Name, country, address, and reduced tax rate.
  • Form W-8BEN-E - Name, country, entity, TIN, Tax benefits, etc.

Refer to Form WhCertificate webhook for a sample payload and to learn how to set up the Webhook URLs.

POST WhCertificate/RequestByUrl
Run in Postman

Request Body

FieldTypeDescription
RequesterObjectCollects the Requester identifier. It can be the TIN (or) the Business Id / PayerRef generated by TaxBandits. If neither is provided, the default Business will be assumed as the Requester.
    PayerRefStringOptional A unique payer identifier that you will assign while requesting the payer information using the endpoint Business/RequestByURL.
Size Range: 1-50
    BusinessIdGuidOptional A unique business identifier generated by TaxBandits after you create a business in your account using the Business endpoint. If you do not provide a BusinessId in the request, the URL will be generated against the default business, i.e., the first business created in your account.
    TINStringOptional Taxpayer Identification Number. Use this as an alternative for BusinessId or PayerRef.
Size Range: 9-11.
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. This identifier will be used in future references of the recipient.
Size Range: 1-50
    NameStringOptional Recipient Name. This will be pre-filled on the Form.
Size Range: ..50
    IsForeignBooleanWhen true, the recipient address is identified as a foreign address (Outside the US). When false, the recipient address is identified as a US address.
Allowed values: "true", "false"
    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 you via Webhooks.
Allowed values: "true", "false"
    CustomizationObjectCollects the customizations such as TIN Service, Business Logo, and Callback URLs.
        BusinessLogoUrlStringOptional Business Logo that will be displayed on the Form completion page.
Size Range: ..150
    RedirectUrlsObjectCollects the RedirectUrls like ReturnUrl and CancelUrl.
        ReturnUrlStringOptional Return Redirection URL. Set the callback URL redirection once the recipient completes filling the Form W-9/W-8BEN.
Size Range: ..150
        CancelUrlStringOptional Cancel Redirection URL. Set the callback URL when the recipient clicks the cancel button on Form W-9/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
    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.

Request JSON

Request URL for Form W-9/W-8 with Payee Reference and opt for TIN Matching. The URLs are provided for business logo customization as well as success and cancel requests.

{
    "Requester": null,
    "Recipient": {
      "PayeeRef": "123456",
      "IsTINMatching": true
    },
    "Customization": 
    {
      "BusinessLogoUrl": "https://www.spanenterprises.com/Content/Images/span.png"
    },
    "RedirectUrls": 
    {
      "ReturnUrl": "https://example.com",
      "CancelUrl": "https://example.com"
    }
    }

Note : You need to provide one of these values - TIN (or) TaxBandits Business Id/PayerRef. If neither is provided, the default Business will be assumed.

Response Body

FieldTypeDescription
SubmissionIdGuidA unique identifier of a submission
PayeeRefStringA unique identifier of the recipient
URLStringURL that can be embedded on your website using Iframe or other means.
Errorsobject[]Collection of errors for the Recipient
IDstringError ID number that is assigned by TaxBandits, and it is unique for each error
NamestringName of the errored node.
MessagestringShows the error message

Response JSON

A unique URL with built-in validations for recipients to complete Form W-9/ W-8BEN/ W-8BEN-E through a secure URL. Since the Requester is not specified, the recipient will be associated with the default business. Business logo and redirection URLs will be rendered.

{
            "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",   
            "PayeeRef": "Pe123451234",
            "Url": "https://testlinks.taxbandits.io?whId=1b9905a5-b5b5-417d-a582-0124994761fb",
            "Errors": null
          }