Skip to main content
Version: 1.6.1

RequestByEmail

This endpoint sends a unique url to the recipients 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 it 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 API endpoint with the following values:

    • Access Token in the header as Bearer Token (Generated using TaxBandits OAuth authentication API)
    • Payee Reference (Unique information that identifies the Recipient. Optional)
    • Name (Recipient Name)
    • Email (Recipient Email)

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

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

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

  5. 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 learn more about webhook set up and sample payloads.

POST FormW8Ben/RequestByEmail

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

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

Request 1 : Send W-8BEN email requests to recipients by giving the BusinessId (Requester) and recipients information.

{ "Requester": {   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",   "TIN": null }, "Recipients": [   {     "PayeeRef": "8987844654654654",     "Name": "Allen Smith",     "Email": "allen.smith@abc.com"   } ]}

Response 1

{ "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": "allen.smith@abc.com",       "W8BenStatus": "ORDER_CREATED",       "StatusTs": "2021-03-09 05:21:56 -05:00"     }   ],   "ErrorRecords": null }, "Errors": null}

Request 2 : Send W-8BEN email requests to recipients by giving the Business TIN (Requester) and recipients information.

{ "Requester": {   "BusinessId": "00000000-0000-0000-0000-000000000000",   "TIN": "22-2222222" }, "Recipients": [   {     "PayeeRef": "8987844654654654",     "Name": "Allen Smith",     "Email": "allen.smith@abc.com"   } ]}

Response 2

{ "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": "allen.smith@abc.com",       "W8BenStatus": "ORDER_CREATED",       "StatusTs": "2021-03-09 05:21:56 -05:00"     }   ],   "ErrorRecords": null }, "Errors": null}

Request 3 : Send W-8Ben email requests to recipients without Requester information (BusinessId or TIN). The recipients will be tied to the default business.

{ "Requester": null, "Recipients": [   {     "PayeeRef": "8987844654654654",     "Name": "Allen Smith",     "Email": "allen.smith@abc.com"   } ]}

Response 3

{ "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": "allen.smith@abc.com",       "W8BenStatus": "ORDER_CREATED",       "StatusTs": "2021-03-09 05:21:56 -05:00"     }   ],   "ErrorRecords": null }, "Errors": null}