Extend your software with TaxBandits IRS E-file API Integration

Skip to main content
Version: 1.7.1

List

Use this method to list the W-9s under a particular business. If you do not have the BusinessId, you can use the TIN to refer the business.

The W-9s can be filtered based on the W-9 Status and Date Range.

GET FormW9/List

Request Body

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
W9StatusStringOptional Status of the W-9
Allowed values: "Sent", "Order_Created", "Scheduled", "URL_Generated", "Opened", "Completed", "Completed_and_TINMatching_Inprogress", "Invalid", "Delivered", "Bounced", "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-9 records to be listed in each page. If the value is not given, then the page size will be defaulted to 100.
FromDateStringOptional List the W-9 records between the date range.
ToDateStringOptional List the W-9 records between the date range.

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.
FormW9RecordsObjectList of W-9 Records
    SubmissionIdGuidSubmission ID of the original W-9 Request
    PayeeRefStringUnique identifier of the recipient
    Line1NmStringRecipient Name as given on the Form W-9 Line 1.
    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
    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 API method RequestByURL
    FormW9RequestTypeStringForm W-9 requested Type. URL_API - Form W-9 was requested using the API method RequestByURL. Email_API - Form W-9 was requested using the API method RequestByEmail. Email_UI - Form W-9 was requested from the TaxBandits UI application.
TotalRecordsIntNumber of records available for the business
TotalPagesIntTotal pages available for the business
PageIntRequested Page Number
PageSizeIntRequested Page Size
ErrorsObjectShows detailed error information.

Request 1 : List with all valid parameters

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

Response 1: The response will list all the W-9s under a given BusinessId and TIN. Here TIN refers to the TIN for Business.

{
"Requester": {
"BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
"BusinessNm": "John Enterprises",
"TINType": "EIN",
"TIN": "22-2222222"
},
"FormW9Records": [
{
"SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
"PayeeRef": "Pe123451234",
"Line1Nm": "ABC Inc",
"W9Status": "COMPLETED",
"StatusTs": "2021-02-19 14:36:28 -05:00",
"TINMatching": {
"Status": "SUCCESS",
"StatusTs": "2021-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": "abc@abcinc.com",
"FormW9RequestType": "URL_API"
},
{
"SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
"PayeeRef": "Pe543221234",
"Line1Nm": "Seve Smith",
"W9Status": "COMPLETED",
"StatusTs": "2021-02-19 14:36:28 -05:00",
"TINMatching": {
"Status": "SUCCESS",
"StatusTs": "2021-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": "steve@abcinc.com",
"FormW9RequestType": "Email_API"
}
],
"TotalRecords": 2,
"TotalPages": 1,
"Page": 1,
"PageSize": 10,
"Errors": null
}

Request 2 : List with BusinessID

FormW9/List?BusinessId=387f41d7-b238-455b-b9d7-48f7d48889f5

Response 2: A response will list all the W-9s that fall under the given BusinessId.

{
"Requester": {
"BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
"BusinessNm": "John Enterprises",
"TINType": "EIN",
"TIN": "22-2222222"
},
"FormW9Records": [
{
"SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
"PayeeRef": "Pe123451234",
"Line1Nm": "ABC Inc",
"W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
"StatusTs": "2021-02-19 14:36:28 -05:00",
"TINMatching": {
"Status": "ORDER_CREATED",
"StatusTs": "2021-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": "abc@abcinc.com",
"FormW9RequestType": "URL_API"
},
{
"SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
"PayeeRef": "Pe543221234",
"Line1Nm": "Seve Smith",
"W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
"TINMatching": {
"Status": "ORDER_CREATED",
"StatusTs": "2021-06-10 07:16:01 -04:00",
"Errors": null
},
"StatusTs": "2021-02-19 14:36:28 -05:00",
"PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
"Email": "steve@abcinc.com",
"FormW9RequestType": "Email_API"
}
],
"TotalRecords": 2,
"TotalPages": 1,
"Page": 1,
"PageSize": 10,
"Errors": null
}

Request 3 : Requesting to list all W-9 for given Business TIN.

FormW9/List?TIN=124563758

Response 3: W-9 corresponds to the given TIN will be listed as an array.

{
"Requester": {
"BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
"BusinessNm": "John Enterprises",
"TINType": "EIN",
"TIN": "22-2222222"
},
"FormW9Records": [
{
"SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
"PayeeRef": "Pe123451234",
"Line1Nm": "ABC Inc",
"W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
"TINMatching": {
"Status": "ORDER_CREATED",
"StatusTs": "2021-06-10 07:16:01 -04:00",
"Errors": null
},
"StatusTs": "2021-02-19 14:36:28 -05:00",
"PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
"Email": "abc@abcinc.com",
"FormW9RequestType": "URL_API"
},
{
"SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
"PayeeRef": "Pe543221234",
"Line1Nm": "Seve Smith",
"W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
"StatusTs": "2021-02-19 14:36:28 -05:00",
"TINMatching": {
"Status": "ORDER_CREATED",
"StatusTs": "2021-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": "steve@abcinc.com",
"FormW9RequestType": "Email_API"
}
],
"TotalRecords": 2,
"TotalPages": 1,
"Page": 1,
"PageSize": 10,
"Errors": null
}

Request 4: List without BusinessID or TIN

FormW9/List?W9Status=COMPLETED_AND_TIN_MATCH_INPROGRESS&Page=1&PageSize=10&FromDate=03/05/2020&ToDate=03/07/2020

Response 4: Since the Requester information was not given, the system will look up for W-9s under default business and return the result.

{
"Requester": {
"BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
"BusinessNm": "John Enterprises",
"TINType": "EIN",
"TIN": "22-2222222"
},
"FormW9Records": [
{
"SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
"PayeeRef": "Pe123451234",
"Line1Nm": "ABC Inc",
"W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
"StatusTs": "2021-02-19 14:36:28 -05:00",
"TINMatching": {
"Status": "ORDER_CREATED",
"StatusTs": "2021-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": "abc@abcinc.com",
"FormW9RequestType": "URL_API"
},
{
"SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
"PayeeRef": "Pe543221234",
"Line1Nm": "Seve Smith",
"W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
"StatusTs": "2021-02-19 14:36:28 -05:00",
"TINMatching": {
"Status": "ORDER_CREATED",
"StatusTs": "2021-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": "steve@abcinc.com",
"FormW9RequestType": "Email_API"
}
],
"TotalRecords": 2,
"TotalPages": 1,
"Page": 1,
"PageSize": 10,
"Errors": null
}

Request 5: List all the W-9s with the status as Invalid.

FormW9/List?W9Status=Invalid

Response 5: A response will list all the W9s with the status as Invalid.

{
"Requester": {
"BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
"BusinessNm": "John Enterprises",
"TINType": "EIN",
"TIN": "22-2222222"
},
"FormW9Records": [
{
"SubmissionId": "8487afa2-ff0e-413e-aa41-ba0b328aac93",
"PayeeRef": "Pe123451234",
"Line1Nm": "ABC Inc",
"W9Status": "INVALID",
"StatusTs": "2021-02-19 14:36:28 -05:00",
"TINMatching": {
"Status": "FAILED",
"StatusTs": "2021-06-10 07:16:01 -04:00",
"Errors": [
{
"Id": "ERR-TINMATCH-007",
"Name": "TIN",
"Message": "SSN should contain 9 digits"
},
{
"Id": "ERR-TINMATCH-029",
"Name": "TIN",
"Message": "SSN should be in proper format"
}
]
},
"PdfUrl": "https://taxbandits-sb-api.s3.amazonaws.com/sample/807f0318-7f5a-4841-9c08-a88b4bf7e7d9.pdf",
"Email": "abc@abcinc.com",
"FormW9RequestType": "URL_API"
}
],
"TotalRecords": 1,
"TotalPages": 1,
"Page": 1,
"PageSize": 1,
"Errors": null
}