Skip to main content
Version: 1.7.3

Status

Status

Use this endpoint to retrieve the status of all Form W-8BEN requests (both complete and incomplete) associated with a specific recipient (payee).

Note:

As an alternative to using this endpoint, you can configure webhooks for the event type 'Form W-8BEN Status Change' webhook. You also have the option to enable web messaging for status updates.

Key Points​

  • If multiple forms exist for the same PayeeRef, all statuses will be returned as an array.
  • If no BusinessId is provided, the API will return the statuses for the recipient with a matching email or PayeeRef linked under your default business.

FormW8BEN Statuses​

StatusApplies to RequestByEmailApplies to RequestByUrl /RequestByBusinessUrlDescription
URL_GENERATED✅✅The URL was generated, but the recipient hasn’t opened it yet.
ORDER_CREATED✅N/AThe request was created but has not yet been processed by TaxBandits.
SCHEDULED✅N/AThe email has been scheduled to be sent to the recipient.
SENT✅N/AW-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/AThe 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.

GET FormW8Ben/Status
Run in Postman

Request Params

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

Response Body

FieldTypeDescription
RequesterObjectRequester information.
    BusinessIdGuidA unique identifier of the business.
    BusinessNmStringBusiness Name of the requester. 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.
PayeeRefStringUnique identifier of the recipient
EmailStringEmail Address of the recipient. This is the email to which the W-8BEN request was sent.
TotalRecordsIntNumber of records available for the Payee Reference
StatusObject[]Statuses of the W-8BEN records for the recipient
Allowed values

"URL_GENERATED" ,"ORDER_CREATED" ,"SCHEDULED" ,"SENT" ,"OPENED" ,"COMPLETED" ,"BOUNCED"

    SubmissionIdGuidSubmission ID of the original W-8BEN Request.
    W8BenStatusStringStatus of the W-8BEN.
    StatusTsStringTimestamp of the W-8BEN Status
    FormW8BenRequestTypeStringForm 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.
ErrorsObjectShows detailed error information.

Request Params​

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

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

Response JSON​

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
}