Skip to main content
Version: 1.7.3

RequestByEmail

This is a payer-initiated method wherein our API endpoint will be used to send an email request to the payees/recipients for the completion of W-8BEN forms.

This endpoint sends a unique url via email to enable the payees to complete their W-8BEN Forms. In order to generate this unique url, the payee’s name and email address are required. Once they complete the Form W-8BEN using this url, you will receive a notification through Webhook regarding the W-8BEN completion.

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] FormW8BEN/RequestByEmail endpoint with the following values:

    • Access Token in the header as Bearer Token (Generated using TaxBandits OAuth authentication API)
    • Payee Reference (Optional) - A unique identifier for each payee who completes Form W-8BEN. This identifier will be used in future references of the payee in the API.
    • Payee Name and Address (Optional) - The payee information will be pre-filled on the form when passed in the request.
    • Requester (Business ID or TIN) (optional) - To identify and save the 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 a Business ID or TIN in the request, the W-8BEN will be associated with the default business, i.e., the first business created in your account.
    • 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-8BEN 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.
      • ShowDownloadPage - Choose whether or not to provide your recipients with the option to download their completed form.

  3. TaxBandits will send the W-8BEN request emails to the payees. The email will have the link to complete Form W-8BEN.

  4. Once the payee completes and signs the Form W-8BEN, you will be notified via Webhook. The Webhook payload will have the W-8BEN information, such as the name, address, EIN/SSN, etc., along with the link to download the completed Form W-8BEN.

    Refer to the Form W-8BEN webhook to learn more about the webhook setup and sample payload.

POST FormW8Ben/RequestByEmail
Run in Postman

Request Body

FieldTypeDescription
RequesterobjectCollects the Requester identifier, i.e., TIN (or) Business ID/PayerRef generated by TaxBandits. If neither is supplied, the default Business will be assumed as the Requester.
    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.
    PayerRefGuidOptionalCollects the Requester identifier, i.e., TIN (or) Business ID/PayerRef generated by TaxBandits. If neither is supplied, the default Business will be assumed as the Requester.
    TINStringOptional Taxpayer Identification Number. Use this as an alternate for BusinessId. (Values: EIN, SSN)
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
Recipientsobject[]Collects the recipient's unique identifier and other basic information that will be pre-filled on the Form.
    PayeeRefStringOptional A unique identifier for each recipient completing the Form W-9 for future reference.
Size Range: 1-50
    NamestringName of the recipient.
Size Range: ..40
    EmailstringEmail Address of the recipient. This is the email address to which the W-9 request email will be sent.
Size Range: ..100
CustomizationIdGuidOptional A unique customization identifier generated by TaxBandits after you complete the customization in the console.
Note: You can customize the W-9/W-8 page (secure URL) with your own logo, fav icon, primary and secondary colors, and email.
CustomizationObjectOptional Collects 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 Optional 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.

Request JSON

Send W-8BEN email requests to recipients by giving the BusinessId (Requester) and recipients information. Make sure the Form W-8BEN Status Change webhook is configured.

{
    "Requester": {
        "BusinessId": null,
        "PayerRef": "Payer1",
        "TIN": "23-0420932",
        "DBAId": "dfb13337-f49b-42fb-b989-07c774a7b81c",
        "DBARef": "#001"
    },
    "Recipients": [
        {
            "PayeeRef": "Pay123",
            "Name": "Mark Davis",
            "Email": "mark@sample.com"
        }
    ]
}

Response Body

FieldTypeDescription
SubmissionIdGuidUnique identifier of a submission.
RequesterObjectRequester information.
    BusinessIdGuidA unique identifier of the business.
    BusinessNmStringRequester Name. If the requester is a Business, then the Business Name will be returned. If the requester is an Individual, then the Payer’s full name will be returned.
    FirstNmStringFirst Name of the Individual
Size Range: ..20
    MiddleNmStringMiddle Name of the Individual
Size Range: ..20
    LastNmStringLast Name of the Individual
Size Range: ..20
    SuffixStringSuffix of the Individual
Allowed values

"Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"

    TINTypeStringTIN Type of the Requester.
    TINStringTaxpayer Identification Number of the requester.
FormW8BENRecordsObjectDetails of Form W-8BEN requests given in the request.
    SuccessRecordsObjectRecipients with no error in the request
        PayeeRefStringUnique identifier of the recipient.
        EmailStringEmail Address of the recipient to which W-8BEN request was sent.
        W8BENStatusStringStatus of the W-8BEN.
        StatusTsStringTimestamp of the W-8BEN status.
    ErrorRecordsObjectDetails of the recipients with errors.
        PayeeRefStringAn unique identifier of a recipient.
        EmailStringEmail Address of the recipient given in the request.
        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.
Errorsobject[]There are a variety of errors in the request. Some of the errors listed under this object are,
  • You should have at-least one business in your account to request W-8BEN
  • Insufficient credits in the account

Response JSON

An email with the link for W-8BEN will be sent to the provided recipient email address. Since the business id is provided, the completed form will save against the same. When a recipient submits the form, the Form W-8BEN Status Change webhook payload will include the W-8BEN data.

{
    "SubmissionId": "b78e2c23-bfa2-49e2-bf2a-f2141dbfa61c",
    "Requester": {
        "BusinessId": "c2a7f62d-ca28-49ae-ac74-cf8b69486545",
        "PayerRef": "Payer1",
        "BusinessNm": "Snowdaze LLC",
        "TINType": "EIN",
        "TIN": "34-9058095",
        "DBAId": "0f51f0c9-ecb4-476b-b48a-976eacbaed2a",
        "DBARef": "3212"
    },
    "FormW8BenRecords": {
        "SuccessRecords": [
            {
                "PayeeRef": "9566647097",
                "Email": "mark@sample.com",
                "W8BenStatus": "ORDER_CREATED",
                "StatusTs": "2024-04-05 11:50:21 -04:00"
            }
        ],
        "ErrorRecords": null
    },
    "Errors": null
}