Skip to main content
Version: 1.7.3

RequestByUrl

This is a payee-initiated method wherein the secure URL provided by the TaxBandits API can 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/W-8 information during the vendor onboarding process. Each vendor who signs in will get a unique URL-embedded page to complete their W9/W-8.

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] FormWHCertificate/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/W-8 form 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.
    • 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/W-8 forms.
    • Business Logo and Callback URLs (Optional) - You can provide your business logo and callback URLs for customization.
    • 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 form submission.

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

  4. 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 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 WhCertificate/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.
TINStringOptionalTaxpayer Identification Number. Use this as an alternative for BusinessId or PayerRef.
Size Range: 9-11
Allowed values : "EIN" , "SSN" (Including hyphen)
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-8BEN 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
AddressObjectOptionalCollects Foreign address details of the recipient.
Address1StringOptionalRecipient’s foreign address line 1 (street address or post office box of that locality). This will be pre-filled on the Form.
Size Range: ..35
Address2StringOptionalRecipient’s foreign address line 2 (suite or apartment number). This will be pre-filled on the Form.
Size Range: ..35
CityStringOptionalRecipient’s Foreign City Name. This will be pre-filled on the Form.
Size Range: ..27
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"

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

Request Json

{
    "Requester": {
        "PayerRef": "B12345",
        "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": "#1be6f5",
        "SecondaryColor": "#9c9276",
        "ShowDownloadPage": true
    },
    "RedirectUrls": {
        "ReturnUrl": "https://example.com",
        "CancelUrl": "https://example.com"
    }
}

Response Body

FieldTypeDescription
SubmissionIdGuidUnique identifier of a submission.
PayeeRefStringUnique identifier of the recipient.
W8BenUrlStringURL 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": "7971f12e-fc8f-4d88-91c9-deb4696d3612",
    "PayeeRef": "123456",
    "Url": "https://testlinks.taxbandits.io?whId=7b20d2c0-6585-435c-89c7-3a01b13d33ef",
    "Errors": null
}
note

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