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?

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

Field	Type	Description
Requester	object	Business 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).
BusinessId	Guid	`Optional` Unique Business Identifier. This ID is generated by TaxBandits after you create a business in your account using the Business endpoint.
TIN	String	`Optional` Taxpayer Identification Number. Use this as an alternative for BusinessId. Values: EIN, SSN Size Range: 9-11(Including hyphen)
Recipients	object[]	Collection of Recipient Name and Email
PayeeRef	String	`Optional` 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
Name	string	Name of the recipient Size Range: 1-40
Email	string	Email 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

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
Requester	Object	Requester information.
BusinessId	Guid	A unique identifier of the business.
BusinessNm	String	Requester 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.
TINType	String	TIN Type of the Requester.
TIN	String	Taxpayer Identification Number of the requester.
FormW8BENRecords	Object	Details of Form W-8BEN requests given in the request.
SuccessRecords	Object	Recipients with no error in the request
PayeeRef	String	Unique identifier of the recipient.
Email	String	Email Address of the recipient to which W-8BEN request was sent.
W8BENStatus	String	Status of the W-8BEN.
StatusTs	String	Timestamp of the W-8BEN status.
ErrorRecords	Object	Details of the recipients with errors.
PayeeRef	String	An unique identifier of a recipient.
Email	String	Email Address of the recipient given in the request.
Errors	object[]	Collection of errors for the recipient.
Id	string	Error ID number. This ID is assigned by TaxBandits and it is unique for each error.
Name	string	Name of the errored node.
Message	string	Shows the error message.
Errors	object[]	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
}

Extend your software with TaxBandits IRS E-file API Integration