Skip to main content
Version: 1.7.3

List

List

Use this endpoint to retrieve all W-9 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 FormW9/List
Run in Postman

Request Params

FieldTypeDescription
BusinessIdGuidOptional A unique identifier of a business. If you do not provide the BusinessId in the request, the BusinessId of the default business will be mapped automatically.
TINStringOptional TIN of the business. If you do not have the BusinessId, you can use the TIN to refer to the business.
Size Range: 9-11
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
W9StatusStringOptional Status of the W-9
Allowed values

"SENT ", "ORDER_CREATED", "SCHEDULED", "URL_GENERATED", "OPENED ", "COMPLETED ", "COMPLETED_AND_TIN_MATCH_INPROGRESS ", "INVALID ", "BOUNCED ", "ALL"

PageintOptional Page number that needs to be listed in the response. If the value is not given, then the page number will default to 1.
PageSizeintOptional Number of W-9 records to be listed on each page. If the value is not given, then the page size will default to 100.
FromDateStringOptional List the W-9 records between the specified date range.
Date format - MM/DD/YYYY
ToDateStringOptional List the W-9 records between the specified date range.
Date format - MM/DD/YYYY

Response Body

FieldTypeDescription
RequesterObjectRequester information.
BusinessIdGuidA unique identifier of the business.
BusinessNmStringRequester 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.
TINTypeStringTIN Type of the requester.
TINStringTaxpayer Identification Number of the requester.
FormW9RecordsObject[]List of W-9 Records
SubmissionIdGuidSubmission ID of the original W-9 Request
DBAIdGuidUnique Identifier for the DBA.
DBARefGuidUnique identifier for each DBA. This identifier can be used in future references of the DBA in the API
RecipientIdGuidA unique identifier generated by TaxBandits for a Recipient. You can use this ID for your future reference to Update.
PayeeRefStringA unique identifier of the recipient
TINTypeStringTIN Type of the requester.
TINStringTaxpayer Identification Number of the requester.
Line1NmStringRecipient Name as given on the Form W-9 Line 1.
Line2NmstringBusiness name/disregarded entity name (if different from Line1 Name)
FirstNmStringFirst Name of the Individual
MiddleNmStringMiddle Name of the Individual
LastNmStringLast Name of the Individual
W9StatusStringStatus of the W-9
StatusTsStringTimestamp of the W-9 Status.
TINMatchingObjectTIN Matching information.
StatusStringTIN Matching status.
StatusTsStringTimestamp of the TIN Matching Status.
ErrorsStringShows the detailed error message.
PdfUrlStringURL to download the completed W-9.
Note: This URL will expire in 24 hours.
EmailStringEmail Address of the recipient. This is the email to which the W-9 request was sent. The value will be null if the Form W-9 was requested using the RequestByUrl method.
FormW9RequestTypeStringForm W-9 requested Type.
  • URL_API - Form W-9 was requested using the RequestByURL method.
  • Email_API - Form W-9 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
ErrorsObject[]Detailed error information.
IdstringError ID number. This ID is assigned by TaxBandits and it is unique for each error.
NamestringName of the errored node.
MessagestringShows the error message

Request Params​

List with all valid parameters

FormW9/List?BusinessId=387f41d7-b238-455b-b9d7-48f7d48889f5&TIN=124563758&W9Status=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": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
 "BusinessNm": "Snowdaze LLC",
 "TINType": "EIN",
 "TIN": "22-2222222"
},
"FormW9Records": [
 {
   "SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
   "DBAId": null,
   "DBARef": null,
   "RecipientId": "69f42424-7703-4f39-bc01-45237e491b6f",
   "PayeeRef": "50367532",
   "TINType": "EIN",
   "TIN": "23-4815851",
   "Line1Nm": "Dairy Delight LLC",
   "Line2Nm": "Coco Milk",
   "FirstNm": null,
   "LastNm": null,
   "MiddleNm": null,
   "Suffix": null,
   "W9Status": "COMPLETED",
   "StatusTs": "2025-02-19 14:36:28 -05:00",
   "TINMatching": {
     "Status": "SUCCESS",
     "StatusTs": "2025-06-10 07:16:01 -04:00",
     "Errors": null
   },
   "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
   "Email": "sample@bodeem.com",
   "FormW9RequestType": "URL_API"
 },
 {
   "SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
   "DBAId": null,
   "DBARef": null,
   "RecipientId": "69f42424-7703-4f39-bc01-45237e491b6f",
   "PayeeRef": "50367532",
   "TINType": "EIN",
   "TIN": "23-4815851",
   "Line1Nm": "Dairy Delight LLC",
   "Line2Nm": "Coco Milk",
   "FirstNm": null,
   "LastNm": null,
   "MiddleNm": null,
   "Suffix": null,
   "W9Status": "COMPLETED",
   "StatusTs": "2025-02-19 14:36:28 -05:00",
   "TINMatching": {
     "Status": "SUCCESS",
     "StatusTs": "2025-06-10 07:16:01 -04:00",
     "Errors": null
   },
   "PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
   "Email": "sample@bodeem.com",
   "CountryPhoneCode": null,
   "Phone": null,
   "FormW9RequestType": "Email_API"
 }
],
"TotalRecords": 2,
"TotalPages": 1,
"Page": 1,
"PageSize": 10,
"Errors": null
}