Skip to main content
Version: 1.7.3

RequestByEmail

This endpoint sends a unique url to the recipients by email to complete their form W-8BEN. The endpoint needs the name and the recipient’s email address to generate the unique url. The recipients will receive an email with the link to complete their W-8BEN in a secured portal. Once the recipients complete the Form W-8BEN, you will receive a webhook notification for the W-8BEN data.

How does this work?

  1. Like any other TaxBandits API Endpoint, the first step is to call the Auth method to get the access token. This access token must be supplied in the request header as the ‘Bearer‘ token. Refer to the OAuth 2.0 Authentication for more information on JWT authentication and how to integrate with the 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)
    • Recipient Name and Address (optional) - The recipient information will be pre-filled on the form when passed in the request.
    • Business Logo and Callback URLs (optional) - Customize the business logo on the Form Form W8-BEN. Set callback redirection URLs upon submission or cancelation. 

  3. Payee Reference (Unique information that identifies the Recipient). Can be the Vendor id, contractor number, recipient email address, or a random number. Will be used to identify the recipient for future references. 

  4. Requester (BusinessId) or TIN- Optional value to save the W8BEN under a particular Business) - 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 supply one in the request, it will be associated with the default business (first business created in your account).

Note: When using this endpoint, the client can send W-8BEN requests to multiple recipients in a single submission.

  1. TaxBandits will send the W-8BEN request emails to the recipients. The email will have the link to complete the Form W-8BEN. The recipient will complete and sign Form W-8BEN through a secure portal. The secured portal can be customized with the client's URL, logo and theme. An electronic signature pad that allows the recipient to sign electronically and submit the form is available.
  2. Once the recipient completes and signs the Form W-8BEN, the client will be notified via Webhook. The Webhook payload will have the W-8BEN data such as the Name, Address and TIN(US/Foreign) along with the link to download the completed Form W-8BEN.

Refer to the Form W-8BEN webhook to know more about webhook set up and sample payload.

POST FormW8Ben/RequestByEmail
Run in Postman

Request Body

FieldTypeDescription
RequesterobjectBusiness you want the W-8BENs to be created under. If you do not supply the requester information, then the W-8BENs will be created using the default business (First business created in your account).
    BusinessIdGuidOptional Unique Business Identifier. This ID is generated by TaxBandits after you create a business in your account using the Business endpoint.
    TINStringOptional Taxpayer Identification Number. Use this as an alternative for BusinessId. Values: EIN, SSN
Size Range: 9-11(Including hyphen)
Recipientsobject[]Collection of Recipient Name and Email
    PayeeRefStringOptional An unique identifier for each recipient completing the Form W-8BEN. This identifier will be used in future references of the recipient in the API.
Size Range: 1-50
    NamestringName of the recipient
Size Range: 1-40
    EmailstringEmail Address of the recipient. This is the email address to which the W-8BEN request email will be sent.
Size Range: 1-50

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": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "TIN": null
 },
 "Recipients": [
   {
     "PayeeRef": "8987844654654654",
     "Name": "Allen Smith",
     "Email": "sample@bodeem.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.
    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": "5a7ddb71-a6ac-4312-ab09-7ad9a2b3507d",
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "FormW8BenRecords": {
   "SuccessRecords": [
     {
      "PayeeRef": "8987844654654654",
       "Email": "sample@bodeem.com",
       "W8BenStatus": "ORDER_CREATED",
       "StatusTs": "2021-03-09 05:21:56 -05:00"
     }
   ],
   "ErrorRecords": null
 },
 "Errors": null
}