Status

Status

Use this endpoint to retrieve the status of Form W-8BEN requests associated with a specific recipient. The endpoint returns both completed and in-progress forms, allowing you to track the recipient’s progress throughout the W-8BEN lifecycle.

Alternative ways to track status

As an alternative to polling this endpoint, you can configure the Form W-8BEN Status Change Webhook to receive real-time status updates. You can also enable web messaging to receive status updates directly in your application.

Key points

• If multiple forms exist for the same recipient (PayeeRef), all associated statuses will be returned.
• If a BusinessId is not provided, TaxBandits will return statuses for the matching recipient under your default business.
• TIN Matching status is returned only for W-8BEN forms where TIN Matching is enabled.

W-8BEN status codes

The following statuses indicate the status of a recipient's W-8BEN request.

Status	Applies to RequestByEmail	Applies to RequestByUrl /RequestByBusinessUrl	Description
URL_GENERATED	✅	✅	The URL was generated, but the recipient hasn’t opened it yet.
ORDER_CREATED	✅	N/A	The request was created but has not yet been processed by TaxBandits.
SCHEDULED	✅	N/A	The email has been scheduled to be sent to the recipient.
SENT	✅	N/A	W-8BEN form email has been sent to the recipient.
OPENED	✅	✅	The recipient has opened the form link but has not completed it.
COMPLETED	✅	✅	The recipient completed and signed the form.
BOUNCED	✅	N/A	The email could not be delivered. This may occur due to: Invalid or non-existent email address - Delivery fails permanently. Update the recipient’s email to resend. Full inbox or temporary issue - Delivery is retried automatically at equal intervals for up to 4 days.

TIN Matching status codes

TIN Matching statuses are available only for Form W-8BEN requests where TIN Matching is enabled.

Status	Description
ORDER_CREATED	TIN Matching order has been created but not yet submitted to the IRS.
SUCCESS	Recipient's Name and TIN match IRS records.
FAILED	Recipient's Name and TIN do not match IRS records.

GET FormW8Ben/Status 

Run in Postman

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)

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 Allowed values "URL_GENERATED" ,"ORDER_CREATED" ,"SCHEDULED" ,"SENT" ,"OPENED" ,"COMPLETED" ,"BOUNCED"
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 RequestByURL method. Email_API - Form W-8BEN was requested using the RequestByEmail method.
Errors	Object	Shows detailed error information.

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 JSON

200

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

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

400

Bad Request Response - You'll get the below response when your API requests contain any validation errors.

{
  "Requester": {
      "BusinessId": "51cd2f9f-046c-47c4-988f-7f83c2bdd3ee",
      "PayerRef": null,
      "BusinessNm": "James  Smith ",
      "FirstNm": null,
      "MiddleNm": null,
      "LastNm": null,
      "Suffix": null,
      "TINType": "SSN",
      "TIN": "650-76-6767"
  },
  "PayeeRef": null,
  "Email": null,
  "CountryPhoneCode": null,
  "PhoneNumber": null,
  "TotalRecords": 0,
  "Status": null,
  "Errors": [
      {
          "Id": "F08-100028",
          "Name": "PayeeRef",
          "Message": "The Payee Reference is not associated with given Business"
      }
  ]
}

401

Unauthorized Response - You'll get the below response when your API requests don't contain valid authentication credentials.

{
  "StatusCode": 401,
  "StatusName": "Unauthorized",
  "StatusMessage": "Invalid authorization credentials",
  "Errors": [
      {
          "Id": "AUTH-100025",
          "Name": "Authorization",
          "Message": "Authorization should not be empty"
      }
  ]
}