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
Field | Type | Description |
---|---|---|
BusinessId | Guid | Optional Unique identifier of a business. If you do not supply the BusinessId in the request, the BusinessId of the default business will be mapped. |
TIN | String | Optional TIN of the business. If you do not have the BusinessId, you can use the TIN to refer the businessSize Range: 9-11 |
W9Status | String | Optional Status of the W-9Allowed values: "Sent", "Order_Created", "Scheduled", "URL_Generated", "Opened", "Completed", "Completed_and_TINMatching_Inprogress", "Invalid", "Delivered", "Bounced", "ALL" |
Page | int | Optional Page number that needs to be listed in the Response. If the value is not given, then the page will be defaulted to 1. |
PageSize | int | Optional 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. |
FromDate | String | Optional List the W-9 records between the date range. |
ToDate | String | Optional List the W-9 records between the date range. |
Response Body
Field | Type | Description |
---|---|---|
Requester | Object | Requester information. |
  BusinessId | Guid | A unique identifier of the business. |
  BusinessNm | String | Requester 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. |
  TINType | String | TIN Type of the Requester. |
  TIN | String | Taxpayer Identification Number of the requester. |
FormW9Records | Object | List of W-9 Records |
  SubmissionId | Guid | Submission ID of the original W-9 Request |
  PayeeRef | String | Unique identifier of the recipient |
  Line1Nm | String | Recipient Name as given on the Form W-9 Line 1. |
  W9Status | String | Status of the W-9 |
  StatusTs | String | Timestamp of the W-9 Status. |
  TINMatching | Object | TIN Matching information. |
    Status | String | TIN Matching status. |
    StatusTs | String | Timestamp of the TIN Matching Status. |
    Errors | String | Shows the detailed error message. |
  PdfUrl | String | URL to download the completed W-9 |
  Email | String | Email 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 |
  FormW9RequestType | String | Form 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. |
TotalRecords | Int | Number of records available for the business |
TotalPages | Int | Total pages available for the business |
Page | Int | Requested Page Number |
PageSize | Int | Requested Page Size |
Errors | Object | Shows 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}