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 in the client’s software or portal, enabling the payees/vendors to start the W-9 completion process on their own.

To complete Form W-9, 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 logs in will get a unique URL-embedded page to complete their W9.

How does this work?​

  1. Call the [POST] FormW9/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 (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.
  • Business Identifier (Business Id or TIN) - This is used to identify and save the W-9 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 TBS-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.
  1. 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-9 Form with built-in validations. Also, there will be an electronic signature pad that allows the payees to sign electronically and submit the form.
  2. Once the payee completes and signs the Form W-9, you will be notified via Webhook. The Webhook payload will have the W-9 information, such as the name, address, and EIN/SSN, along with the link to download the completed Form W-9.

Refer to Form W-9 webhook to learn more about webhook setup and sample payload.

  1. If **IsTINMatching **is set to ‘TRUE’, TaxBandits will validate the payee’s Name, TIN, and TINType against the IRS database. The TIN Matching status of the payee (Success or Failed) will be posted on the same Webhook URL configured for Form W-9 status change.

    If the Name and TIN given by the payees do not match with the IRS database, the W-9 will become invalid, and you have to request a new Form W-9 from the respective payee.

POST FormW9/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.
    TINStringOptional Taxpayer 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-9 that 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 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
        CityStringOptional Recipient US City. This will be pre-filled on the Form.
Size Range: ..50
        StatestringOptional Recipient 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"

        ZipCdStringOptional Recipient Zip Code. In the format 99999 or 99999-9999. This will be pre-filled on the Form.
Size Range: 5..10
    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.
Allowed values: "true", "false"
    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
    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

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

Request JSON

Request W-9 URL just by using Payee Reference. The URL will be generated for the default business defined in the TaxBandits application for your account. (Make sure the Form W-9 Status Change Webhook is configured.)

{
  "Recipient": {
    "PayeeRef": "Pe464522"
  }
}

Response Body

FieldTypeDescription
SubmissionIdGuidA Unique identifier of a submission.
PayeeRefStringA Unique identifier of the recipient.
W9UrlStringURL that can be embedded on the client's website using Iframe or other means.
ErrorsObject[]Shows error information. This object will list the errors in the request parameters.
    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

A distinctive URL is generated for specific PayeeRef and BusinessID. The completed form will be saved against the BusinessID provided. Upon submission, Webhook payload status will include W-9 and TIN Matching statuses, if opted.

{
    "SubmissionId": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
    "PayeeRef": "Pe464522",    
    "W9Url": "https://testlinks.taxbandits.io?uId=230871f3-4cc9-4848-9f79-2f6964eaca27",
    "Errors": null
}