Skip to main content
Version: 1.7.3

List

List

Use this endpoint to retrieve all W-8BEN forms associated with a specific payer. You can filter the records by status, date range, and form type.

This endpoint is useful for building dashboard views, generating audit exports, and supporting bulk processing workflows.

Key points​

  • BusinessId is required to retrieve forms for a specific payer.
  • Filter by status to view only Pending, Completed, Expired, or Invalid records.
  • Results are paginated. Use the page and pageSize parameters to control the number of records returned.
GET FormW8Ben/List
Run in Postman

Request Params

FieldTypeDescription
BusinessIdGuidOptional Unique identifier of a business. If you do not supply the BusinessId in the request, the BusinessId of the default business will be mapped.
TINStringOptional TIN of the business. If you do not have the BusinessId, you can use the TIN to refer the business
Size Range: 9-11 (including hypen)
RecipientIdGuidOptional A unique identifier generated by TaxBandits for a Recipient. You can use this ID for your future reference to Update.
PayeeRefStringOptional A unique identifier for each payee completing their information.
RecipientLast4TINStringOptional Last four digits of Taxpayer Identification Number. Use this as an alternate for BusinessId.
Size Range: 4
W8BENStatusStringOptional Status of the W-8BEN
Allowed values

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

PageintOptional Page number that needs to be listed in the Response. If the value is not given, then the page will be defaulted to 1.
PageSizeintOptional Number of W-8BEN records to be listed in each page. If the value is not given, then the page size will be defaulted to 100.
FromDateStringOptional Lists the W-8BEN records between the date range.
ToDateStringOptional Lists the W-8BEN records between the date range.

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.
FormW8BENRecordsObject[]List of W-8BEN Records.
SubmissionIdGuidSubmission ID of the original W-8BEN Request
PayeeRefStringUnique identifier of the recipient
RecipientIdGuidA unique identifier generated by TaxBandits for a Recipient. You can use this ID for your future reference to Update.
USTINTypestringTIN type of the recipient. Either SSN or ITIN.
USTINstringRecipient’s TIN
NmOfIndividualStringRecipient Name as given on the Form W-8BEN Line 1.
W8BENStatusStringStatus of the W-8BEN.
StatusTsStringTimestamp of the W-8BEN Status
PdfUrlStringURL to download the completed W-8BEN .
Note: This URL will expire in 24 hours.
EmailStringEmail Address of the recipient. This is the email to which the W-8BEN request was sent.The value will be null if the Form W-8BEN was requested using the API method RequestByURL
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.
TotalRecordsIntNumber of records available for the business
TotalPagesIntTotal pages available for the business
PageIntRequested Page Number
PageSizeIntRequested Page Size
ErrorsObjectShows detailed error information.

Request Params​

List with all valid parameters

FormW8Ben/List?BusinessId=387f41d7-b238-455b-b9d7-48f7d48889f5&TIN=124563758&W8BENStatus=Completed&Page=1&PageSize=10&FromDate=03/05/2025&ToDate=03/07/2025

Response JSON​

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

{
"Requester": {
  "BusinessId": "387f41d7-b238-455b-b9d7-48f7d48889f5",
  "BusinessNm": "Snowdaze LLC",
  "TINType": "EIN",
  "TIN": "12-4563758"
},
"FormW8BenRecords": [
  {
    "SubmissionId": "e2940f7c-78df-4495-b00f-4a144fe9bce2",
    "RecipientId": "ac3c80e1-1e6a-495d-abc1-dff3b030504e",
    "PayeeRef": "123457",
    "USTINType": "SSN",
    "USTIN": "345-78-7563",
    "NmOfIndividual": "John Thomas",
    "FirstNm": "John",
    "MiddleNm": null,
    "LastNm": "Thomas",
    "Suffix": null,
    "W8BENStatus": "COMPLETED",
    "StatusTs": "2025-10-31 06:56:56 -04:00",
    "PdfUrl": "https://s3.amazonaws.com/taxbandits-dev-api/aa87ac84-666a-4763-12f6-fb8b73434b7d.Pdf",
    "Email": null,
    "CountryPhoneCode": null,
    "Phone": null,
    "FormW8BENRequestType": "COMMON_URL_API",
    "DBARef": null,
    "DBAId": "00000000-0000-0000-0000-000000000000"
  },
  {
    "SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
    "RecipientId": "d94f8462-d509-4636-98dc-aef25fe50ea3",
    "USTINType": "SSN",
    "USTIN": "345-78-8763",
    "PayeeRef": "Pe543221234",
    "NmOfIndividual": "Steve Smith",
    "FirstNm": "John",
    "MiddleNm": null,
    "LastNm": "Thomas",
    "Suffix": null,
    "W8BENStatus": "COMPLETED",
    "StatusTs": "2025-02-19 14:36:28 -05:00",
    "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
    "Email": "mark@sample.com",,
    "CountryPhoneCode": null,
    "Phone": null,
    "FormW8BENRequestType": "COMMON_URL_API",
    "DBARef": null,
    "DBAId": "00000000-0000-0000-0000-000000000000"
  }
],
"TotalRecords": 2,
"TotalPages": 1,
"Page": 1,
"PageSize": 10,
"Errors": null
}