Skip to main content
Version: 1.7.3

List

List

Use this endpoint to retrieve all W-9/W-8 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 WhCertificate/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
WhCertificateStatusStringOptional Status of the Withholding form.
Allowed values

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

FormTypeStringOptional Denotes the type of Withholding form
Allowed values

"FORMW9", "FORMW8BEN", "FORMW8BENE", "FORMW8ECI", "FORMW8IMY", "FORMW8EXP"

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 Withholding forms records to be listed on each page. If the value is not given, then the page size will default to 100.
FromDateStringOptional List the Withholding forms records between the specified date range.
Date format - MM/DD/YYYY
ToDateStringOptional List the Withholding forms 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.
WhcertificateRecordsObject[]List of Withholding forms Records
    SubmissionIdGuidSubmission ID of the original WhCertifiacte 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
    FormTypeStringDenotes the type of Withholding form
    Line1NmStringRecipient Name as given on the Form W-9 Line 1.
    DBANameStringName of the DBA.
    FirstNmStringFirst Name of the Individual
    MiddleNmStringMiddle Name of the Individual
    LastNmStringLast Name of the Individual
    SuffixStringSuffix of the Individual
    Ch3StatusStringChapter 3 status code of the recipient
    Ch4StatusStringChapter 4 status code of the recipient
    TINTypeStringTIN type of the recipient
    TINStringTIN of the Recipient (SSN, ITIN, ATIN, or EIN).
    IsFTINLegallyRequiredBooleanIf true identifies that the recipeint does not need to provide the FTIN
    FTINStringFTIN of the recipeint
    GIINStringGIIN of the recipeint
    EmailStringRecipient's email address.
    PhoneStringThe phone number of the recipient.
    CountryPhoneCodeStringRecipient’s country code.
    StatusStringStatus of the Withholding forms
    StatusTsStringTimestamp of the Withholding form Status.
    IsTINMatchingBooleanTIN Matching will be enabled when the value is set as True
    TINMatchingStatusStringTIN matching status of the recipeint
    PdfUrlStringURL of the completed withholding form PDF
    RequestTypeStringWhCertificate requested Type.
  • COMMON_URL_API - WhCertificate was requested using the RequestByURL method.
  • COMMON_EMAIL_API - WhCertificate was requested using the RequestByEmail method.
    RequestedTsStringRequested timestamp of the WhCertificate
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

Whcertificate/List?BusinessId=387f41d7-b238-455b-b9d7-48f7d48889f5&TIN=124563758&WhCertificateStatus=COMPLETED&FormType=W8ECI&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": "f09b41b8-8b91-4953-b489-d12653a1950f",
      "BusinessNm": "SnowDaze LLC",
      "PayerRef": null,
      "FirstNm": null,
      "MiddleNm": null,
      "LastNm": null,
      "Suffix": null,
      "TINType": "EIN",
      "TIN": "34-8388437"
  },
  "WhcertificateRecords": [
      {
          "SubmissionId": "27c684ba-6dac-40e1-b484-3fec49297ac9",
          "DBAId": null,
          "DBARef": null,
          "RecipientId": "27a2cb09-32c8-4d25-9f8a-142b44c90d08",
          "PayeeRef": "Pe9495",
          "FormType": "FormW9",
          "Line1Nm": "ABC LLC",
          "Line2Nm": "Techco",
          "FirstNm": null,
          "LastNm": null,
          "MiddleNm": null,
          "Suffix": null,
          "NmOfIndividual": null,
          "NmOfOrganization": null,
          "BusinessNm": null,
          "Ch3Status": null,
          "Ch4Status": null,
          "TINType": "EIN",
          "TIN": "XX-XXX4672",
          "IsFTINLegallyRequired": false,
          "FTIN": null,
          "GIIN": null,
          "Email": "james@sample.com",
          "CountryPhoneCode": "US",
          "Phone": "5241898753",
          "Status": "COMPLETED",
          "StatusTs": "2025-05-20 05:43:46 -04:00",
          "IsTINMatching": false,
          "TINMatching": null,
          "PdfUrl": "https://s3.amazonaws.com/taxbandits-dev-api/0e39d494-fc58-4819-7679-17b20d3fc722.Pdf",
          "RequestType": "COMMON_PHONE_API",
          "RequestedTs": "2025-05-20 05:42:31 -04:00"
      },
      {
          "SubmissionId": "07186b75-51ea-4fa2-8ccc-d7ec9dba9168",
          "DBAId": null,
          "DBARef": null,
          "RecipientId": "023a1a06-3dd6-457f-a03e-93706eb174d6",
          "PayeeRef": "Pe9496",
          "FormType": "FormW8BEN",
          "Line1Nm": null,
          "Line2Nm": null,
          "FirstNm": "John",
          "LastNm": "Smith",
          "MiddleNm": null,
          "Suffix": "III",
          "NmOfIndividual": "John Smith III",
          "NmOfOrganization": null,
          "BusinessNm": null,
          "Ch3Status": null,
          "Ch4Status": null,
          "TINType": "SSN",
          "TIN": "XXX-XX-7319",
          "IsFTINLegallyRequired": false,
          "FTIN": "45262739899",
          "GIIN": null,
          "Email": null,
          "CountryPhoneCode": null,
          "Phone": null,
          "Status": "COMPLETED",
          "StatusTs": "2025-05-20 05:49:03 -04:00",
          "IsTINMatching": false,
          "TINMatching": null,
          "PdfUrl": "https://s3.amazonaws.com/taxbandits-dev-api/9dedd85c-9d78-420b-8358-5a17a5o0a983.Pdf",
          "RequestType": "COMMON_URL_API",
          "RequestedTs": "2025-05-20 05:44:46 -04:00"
      },
      {
          "SubmissionId": "e2f12905-a586-4b88-a05c-0e000a7969b3",
          "DBAId": null,
          "DBARef": null,
          "RecipientId": "023a1a06-3dd6-457f-a03e-93706eb174d6",
          "PayeeRef": "Pe9496",
          "FormType": "FormW8BENE",
          "Line1Nm": null,
          "Line2Nm": null,
          "FirstNm": null,
          "LastNm": null,
          "MiddleNm": null,
          "Suffix": null,
          "NmOfIndividual": null,
          "NmOfOrganization": "SnowDaze LLC ",
          "BusinessNm": null,
          "Ch3Status": "GRANTOR TRUST",
          "Ch4Status": "PARTICIPATING FFI",
          "TINType": "SSN",
          "TIN": "XXX-XX-2332",
          "IsFTINLegallyRequired": false,
          "FTIN": "836587454365",
          "GIIN": "263237.76723.SB.857",
          "Email": null,
          "CountryPhoneCode": null,
          "Phone": null,
          "Status": "COMPLETED",
          "StatusTs": "2025-05-20 05:52:07 -04:00",
          "IsTINMatching": false,
          "TINMatching": null,
          "PdfUrl": "https://s3.amazonaws.com/taxbandits-dev-api/2dba5600-5721-447e-9a2a-361a4768dbb.Pdf",
          "RequestType": "Email_API",
          "RequestedTs": "2025-05-20 05:49:30 -04:00"
      },
      {
          "SubmissionId": "e6a8393c-2ba6-443c-8770-6434a4a8d377",
          "DBAId": null,
          "DBARef": null,
          "RecipientId": "023a1a06-3dd6-457f-a03e-93706eb174d6",
          "PayeeRef": "Pe9496",
          "FormType": "FormW8ECI",
          "Line1Nm": null,
          "Line2Nm": null,
          "FirstNm": "James",
          "LastNm": "Smith",
          "MiddleNm": null,
          "Suffix": "Sr",
          "NmOfIndividual": null,
          "NmOfOrganization": null,
          "BusinessNm": null,
          "Ch3Status": null,
          "Ch4Status": null,
          "TINType": "SSN",
          "TIN": "XXX-XX-1236",
          "IsFTINLegallyRequired": true,
          "FTIN": null,
          "GIIN": null,
          "Email": null,
          "CountryPhoneCode": null,
          "Phone": null,
          "Status": "COMPLETED",
          "StatusTs": "2025-05-20 05:56:48 -04:00",
          "IsTINMatching": false,
          "TINMatching": null,
          "PdfUrl": "https://s3.amazonaws.com/taxbandits-dev-api/3f27b2b5-6f02-49fa-8sf6-9f40570135ef.Pdf",
          "RequestType": "Email_API",
          "RequestedTs": "2025-05-20 05:52:18 -04:00"
      }
  ],
  "TotalRecords": 4,
  "TotalPages": 1,
  "Page": 1,
  "PageSize": 100,
  "Errors": null
}