Skip to main content
Version: 1.7.3

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. Like any other TaxBandits API Endpoint, the first step is to call the notification to get the access token. This access token must be provided in the request header as the ‘Bearer‘ token. Refer to the OAuth 2.0 Authentication for more information on JWT authentication and integrating with subsequent requests.

  2. The second step is to call the [POST] FormW9/RequestByUrl endpoint with the following values:

    • 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).
    • Payee Name and Address (Optional) - The payee information will be pre-filled on the form when passed in the request.
    • 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 TaxBandits-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
    • DBA Reference (Optional) - If you have multiple DBA names for your business, you can provide the DBA name you want to use as the Requester Name on W-9 forms.
    • Customizations (Optional) - You can provide the following things in your request for customization.
      • Business Logo - You can provide your business logo and its position.
      • Color Theme - Specify the primary and secondary colors of the page.
      • Interview-Style - As an alternative to direct-form entry, provide your recipients with an interview-style W-9 completion.
      • ShowDownloadPage - Choose whether or not to provide your recipients with the option to download their completed form.
      • RedirectUrls - Set the URLs to which you want the recipients to be redirected once they complete/cancel the W-9 submission.

  3. 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.

  4. 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 the Form W-9 webhook to learn more about webhook setup and sample payload.

note

Web Messaging

Instead of webhook, you can choose to receive notifications via web messaging. For more information, click here.

  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 Json

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
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
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
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.
CustomizationIdGuidOptional A unique customization identifier generated by TaxBandits after you complete the customization in the console.

Note: You can customize the W-9 page (secure URL) with your own logo, fav icon, primary and secondary colors, and email.
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
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

Request Json

Request URL for Form W-9 with Payer Reference and opt for Customization and TIN Matching

{
    "Requester": {
        "PayerRef": "D12345",
        "BusinessId": null,
        "TIN": null,
        "DBAId": null,
        "DBARef": null

    },
    "Recipient": {
        "PayeeRef": "123456",
        "Name": "John",
        "IsTINMatching": true
    },
    "Customization": {
        "BusinessLogoUrl": "https://www.spanenterprises.com/Content/Images/span.png",
        "LogoPosition": "CENTER",
        "InterviewFlow": true,
        "PrimaryColor": "#E61A1A",
        "SecondaryColor": "#18F244",
        "ShowDownloadPage": true
    },
    "RedirectUrls": {
        "ReturnUrl": "https://example.com",
        "CancelUrl": "https://example.com"
    }
}

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

Response JSON

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