Version: 1.7.0

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 business Size Range: 9-11
W9Status	String	`Optional` Status of the W-9 Allowed 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
}

Extend your software with TaxBandits IRS E-file API Integration