Status

This method will return the status of all the Form W-8BENs (complete and incomplete) for a particular recipient.

The statuses of the W-8BENs that were requested using the endpoints RequestByURL, RequestByEmail and TaxBandits application can be retrieved using this method.

W-8BEN Statuses

• URL Generated - The W-8BEN URL is generated by TaxBandits, but the recipient has not opened it. (Not applicable to RequestByEmail method).
• Order Created - The client requested W-8BEN using the RequestByEmail method and it has not yet been processed by TaxBandits. (Not applicable to RequestByURL method).
• Scheduled - The TaxBandits email service has taken up the W-8BEN request and the email is scheduled to be sent. (Not applicable to RequestByURL method)
• Sent - Client sent W-8BEN request from TaxBandits API and the email has yet to be delivered. (Not applicable to RequestByURL method).
• Opened - The recipient has opened the Form W-8BEN and has yet to complete it.
• Completed - Recipient has completed and signed the Form W-8BEN

Key Points

• If there are multiple W-8BENs for the same Email or PayeeRef, the statuses of all the W-8BENs will be listed as an array.
• If you do not supply the BusinessId in the request, then the status of the W-8BEN that matches the Email or PayeeRef linked to the default business will be retrieved.

GET FormW8Ben/Status 

Request Params

Field	Type	Description
PayeeRef	String	Unique identifier of a recipient. Either PayeeRef or Email is required. Size Range: 1-50
Email	String	Email Address of the recipient. Size Range: 1-50
BusinessId	Guid	Optional Unique Business Identifier. If you do not supply the BusinessId in the request, the BusinessId of the default business will be mapped.
TIN	String	Optional Taxpayer Identification Number. Use this as an alternate for BusinessId. Values: EIN, SSN Size Range: 9-11(Including hyphen)

Request Params

Sample 1

Get the W-8BEN status of a recipient with PayeeRef and BusinessId.

FormW8Ben/Status?PayeeRef=Pe123451234&BusinessId=7B82B242-1223-4029-9251-C0446298F620

Sample 2

Get the W-8BEN status of a recipient with Email and BusinessId.

FormW8Ben/Status?Email=steve@abcinc.com&BusinessId=7746f0cd-e8eb-4428-9240-12ea84160ee8

Sample 3

Get the W-8BEN status of a recipient with PayeeRef and TIN.

FormW8Ben/Status?PayeeRef=Pe123451234&TIN=22-2222222

Sample 4

Get the W-8BEN status of a recipient with PayeeRef and no Requester (BusinessId or TIN) information.

FormW8Ben/Status?PayeeRef=Pe123451234

Response Body

Field	Type	Description
Requester	Object	Requester information.
BusinessId	Guid	A unique identifier of the business.
BusinessNm	String	Business Name of the requester. 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.
PayeeRef	String	Unique identifier of the recipient
Email	String	Email Address of the recipient. This is the email to which the W-8BEN request was sent.
TotalRecords	Int	Number of records available for the Payee Reference
Status	Object[]	Statuses of the W-8BEN records for the recipient
SubmissionId	Guid	Submission ID of the original W-8BEN Request.
W8BenStatus	String	Status of the W-8BEN.
StatusTs	String	Timestamp of the W-8BEN Status
FormW8BenRequestType	String	Form W-8BEN requested Type. URL_API - Form W-8BEN was requested using the API method RequestByURL. Email_API - Form W-8BEN was requested using the API method RequestByEmail. Email_UI - Form W-8BEN was requested from the TaxBandits UI application.
Errors	Object	Shows detailed error information.

Response JSON

Response 1

A response will provide the status of W-8BEN for the specific PayeeRef and BusinessId.

{
 "Requester": {
   "BusinessId": "7B82B242-1223-4029-9251-C0446298F620",
   "BusinessNm": "Snowdaze LLC",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "Email": "sample@bodeem.com",
 "TotalRecords": 1,
 "Status": [
   {
     "SubmissionId": "85dd7845-55b0-4b1d-9f1b-17a6f51c4dea",
     "W8BenStatus": "COMPLETED",
     "StatusTs": "2021-02-22 04:24:09 -05:00",
     "FormW8BenRequestType": "URL_API"
   }
  ],
 "Errors": null
}

Response 2

This recipient was sent multiple requests to complete W-8BEN using the same PayeeRef.

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "Snowdaze LLC",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "Email": "sample@bodeem.com",
 "TotalRecords": 2,
 "Status": [
   {
     "SubmissionId": "85dd7845-55b0-4b1d-9f1b-17a6f51c4dea",
     "W8BenStatus": "OPENED",
     "StatusTs": "2021-02-22 04:24:09 -05:00",
     "FormW8BenRequestType": "URL_API"
   },
   {
     "SubmissionId": "65c6dc7a-c659-4f42-af26-bcd1ccf07432",
     "W8BENStatus": "COMPLETED",
     "StatusTs": "2021-02-22 04:24:30 -05:00",
     "FormW8BENRequestType": "EMAIL_API"
   }
 ],
 "Errors": null
}

Response 3

W-8BEN status will be retrieved for the given PayeeRef and TIN.

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "Snowdaze LLC",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "Email": "sample@bodeem.com",
 "TotalRecords": 1,
 "Status": [
   {
     "SubmissionId": "85dd7845-55b0-4b1d-9f1b-17a6f51c4dea",
     "W8BenStatus": "OPENED",
     "StatusTs": "2021-02-22 04:24:09 -05:00",
     "FormW8BenRequestType": "URL_API"
   }
 ],
 "Errors": null
}

Response 4

Since the Requester information was not given, the system will look for W-8BENs under the default business and return the result .

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "Snowdaze LLC",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "Email": "sample@bodeem.com",
 "TotalRecords": 1,
 "Status": [
   {
     "SubmissionId": "85dd7845-55b0-4b1d-9f1b-17a6f51c4dea",
     "W8BenStatus": "OPENED",
     "StatusTs": "2021-02-22 04:24:09 -05:00",
     "FormW8BenRequestType": "URL_API"
   }
 ],
 "Errors": null
}