Skip to main content
Version: 1.7.3

RequestByEmail

RequestByEmail

This is a payer-initiated method where the API sends a secure, personalized email to each payee with a unique URL to complete Form W-8BEN online. Each URL is scoped to that specific payee.

This method is useful when you already have a list of foreign individual payees and want TaxBandits to send the form request email on your behalf.

When to use​

  • You have the complete list of foreign individual payees and their email addresses on file.
  • You want each payee to receive a personalized email invitation with available details pre-filled.
  • You prefer TaxBandits to handle email delivery rather than sending the request through your own system.
  • You need to collect Form W-8BEN before determining withholding and reporting requirements for U.S.-source payments.

If recipients are more likely to respond to an SMS, use RequestByText instead.

How it works​

  1. Authenticate

    Obtain a Bearer token via the OAuth 2.0 flow and include it in all request headers.

  2. Ensure a business (payer) exists

    Before calling this endpoint, confirm the payer has been created using the Business endpoint. If no BusinessId is provided in the request, the request will be associated with the default payer (the first payer created in your account).

  3. Call the endpoint

    Along with the payer and recipient details, your request may include the following optional parameters:

    • DBAId / DBARef — Scope the URL to a specific DBA under the payer. The DBA name will appear as the requester on the form.
    • Customization — Apply your logo and primary/secondary colors to brand the form page. Alternatively, pass a CustomizationId generated from the PortalCustomization endpoint.
    • EmailCustomization — Customizes the email sent to the recipient. You can apply your logo, primary/secondary colors, sender name, and sender email address, Email Subject, and Email body to brand the email. Alternatively, pass an EmailCustomizationId generated from the EmailCustomization endpoint.
    • InterviewFlow — Set to TRUE to present the W-8BEN as a guided interview rather than a traditional form.
    • PrefLang — Specify the language for the form. Recipients can also change their preferred language if needed. Supported languages: English, French, Spanish, German, Ukrainian, and Portuguese.
    • IsReminderEnabled — Set automated reminders to recipients who haven’t completed their forms.
    Automate TIN Matching

    Set IsTINMatching to TRUE to automatically trigger IRS TIN Matching once the recipient submits their form.

  4. Recipient completes the form

    TaxBandits sends the email request to the recipient. When the recipient opens the secure URL, they can complete, e-sign, and submit Form W-8BEN online.

  5. Get notified

    Once a recipient submits, you can receive notification through any of the following:

    • Webhooks — Configure the Form W-8BEN Status Change webhook event to receive a payload with the recipient's name, TIN, address, and a link to download the completed form. Learn more
    • Status endpoint — Poll the Status endpoint on demand to retrieve the current form status for a given recipient.
    • Web messaging — Receive in-browser notifications when a recipient completes their form. Learn more
POST FormW8Ben/RequestByEmail
Run in Postman

Request Body

FieldTypeDescription
SubmissionManifestobjectSubmissionManifest provides brief information about submission and the services opted for.
IsReminderEnabledBooleanOptional When enabled, reminder emails are triggered if the withholding certificate is not completed
ReminderSchdDaysNumberFrequency of reminder emails sent to complete W-9/W-8 forms.
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.
PayerRefStringOptionalCollects 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-8BEN 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-8BEN request email will be sent.
Size Range: ..100
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.
CustomizationIdGuidOptional A unique identifier generated by TaxBandits upon completing the portal customization in the Developer Console, or returned in the response from the PortalCustomization/Create endpoint.
EmailCustomizationIdGuidOptional A unique identifier generated by TaxBandits upon completing the email customization in the Developer Console, or returned in the response from the EmailCustomization/Create endpoint.
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.
PrefLangStringOptionalLanguage Preference of the form
Allowed values

"en-US", "es-ES", "fr-FR","de-DE","uk-UA","pt-PT"

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

Request JSON​

{
"SubmissionManifest": {
      "IsReminderEnabled": true,
      "ReminderSchdDays": 10
  },
  "Requester": {
      "BusinessId": null,
      "TIN": "23-0420932",
      "DBAId": "dfb13337-f49b-42fb-b989-07c674a7b81c",
      "DBARef": "#001",
      "PayerRef": "Payer1"
  },
  "Recipients": [
      {
          "PayeeRef": "Pay123",
          "Name": "Mark Davis",
          "Email": "mark@sample.com"
      }
  ],
  "WebhookRef": "2E9C7CA0-F0CF-4257-99AA-7FD6CCFD9D4"
}

Response JSON​

Success Response - This is a sample response for successful API requests.

{
  "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
}