Version: 1.7.3

Status

This method will return the status of all the Form W-9s (complete and incomplete) for a particular recipient.

The statuses of the W-9s that were requested using the endpoints RequestByURL, RequestByEmail and TaxBandits application can be retrieved using this method.

W-9 Statuses:

URL Generated - The W-9 URL is generated by TaxBandits, but the recipient has not opened it. (Not applicable to RequestByEmail method)
Order Created - The client requested W-9 using RequestByEmail method and it is not yet processed by TaxBandits. (Not applicable to RequestByURL method)
Scheduled - The TaxBandits email service has taken up the W-9 request and the email is scheduled to be sent. (Not applicable to RequestByURL method)
Sent - Email with the url to complete W-9 has been sent to the recipients. (Not applicable to RequestByURL method)
Opened - The recipient has opened the URL, viewed the respective form, but yet to complete it.
Completed - Recipient has completed and signed the Form W-9.
Completed_and_Tin_Match_InProgress - Form W-9 has been completed and if TIN Matching is opted, the process will kick start. TIN Matching is applicable only for completed Form W-9.
Invalid - TIN given by the recipient does not match with the IRS database and the W-9 has become invalid.

TIN Statuses:

Order Created - Recipient completed the Form W-9 and a TIN Matching order is created in TaxBandits. You will receive a Webhook notification for this status.
Under Process - Our system has batched the TIN Requests and is queued for IRS submission.
Sent to Agency - The order has been sent to the IRS for TIN verification and TaxBandits is waiting for the response from the IRS. Usually the IRS takes one business day to complete the TIN verification process.
Success - Recipient’s Name and TIN combination matches with the records in the IRS database.
Failed - Recipient’s Name and TIN combination does not match with the records in the IRS database.

Key Points

If there are multiple W-9s for the same Email or PayeeRef, the statuses of all the W-9s will be listed as an array.
If you do not supply the BusinessId in the request, then the status of the W-9 that matches the Email or PayeeRef linked to the default business will be retrieved.

GET FormW9/Status

Request Body

Field	Type	Description
PayeeRef	String	Unique identifier of a recipient. Either PayeeRef or Email is required. Size Range: 1-50
Email	String	Email Address of the recipient. Size Range: 1-50
BusinessId	Guid	`Optional` Unique Business Identifier. If you do not supply the BusinessId in the request, the BusinessId of the default business will be mapped.
TIN	String	`Optional` Taxpayer Identification Number. Use this as an alternate for BusinessId. Values: EIN, SSN Size Range: 9-11

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
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.
PayeeRef	String	Unique identifier of the recipient
Email	String	Email Address of the recipient. This is the email to which the W-9 request was sent.
TotalRecords	Int	Number of records available for the Payee Reference
Status	Object[]	Statuses of the W-9 records for the recipient
SubmissionId	Guid	Submission ID of the original W-9 Request
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.
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.
Errors	Object	Shows detailed error information.

Request 1: Get W-9 status of a recipient with PayeeRef and BusinessId.

FormW9/Status?PayeeRef=Pe123451234&BusinessId=7B82B242-1223-4029-9251-C0446298F620

Response 1: A response will provide the status of W-9 for the specific Payee Reference and BusinessId.

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "Email": "steve@abcinc.com",
 "TotalRecords": 1,
 "Status": [
   {
     "SubmissionId": "85dd7845-55b0-4b1d-9f1b-17a6f51c4dea",
     "W9Status": "COMPLETED",
     "StatusTs": "2021-02-22 04:24:09 -05:00",
     "TINMatching": {
       "Status": "SUCCESS",
       "StatusTs": "2021-06-21 08:00:35 -04:00",
       "Errors": null
     },
     "FormW9RequestType": "URL_API"
   }
 ],
 "Errors": null
}

Request 2 : Get W-9 status of a recipient with Email and BusinessId.

FormW9/Status?Email=steve@abcinc.com&BusinessId=7B82B242-1223-4029-9251-C0446298F620

Response 2 : Statuses of the W-9s are listed as an array. This recipient was requested to complete W-9 multiple times using the same PayeeRef.

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "Email": "steve@abcinc.com",
 "TotalRecords": 2,
 "Status": [
   {
     "SubmissionId": "85dd7845-55b0-4b1d-9f1b-17a6f51c4dea",
     "W9Status": "OPENED",
     "StatusTs": "2021-02-22 04:24:09 -05:00",
     "TINMatching": null,
     "FormW9RequestType": "URL_API"
   },
   {
     "SubmissionId": "65c6dc7a-c659-4f42-af26-bcd1ccf07432",
     "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-02-22 04:24:30 -05:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-06-10 07:16:01 -04:00",
       "Errors": null
     },
     "FormW9RequestType": "EMAIL_API"
   }
 ],
 "Errors": null
}

Request 3 : Get W-9 status of a recipient with PayeeRef and TIN.

FormW9/Status?PayeeRef=Pe123451234&TIN=003313330

Response 3: W-9 status will be retrieved for the given Payee Reference and TIN.

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "Email": "steve@abcinc.com",
 "TotalRecords": 1,
 "Status": [
   {
     "SubmissionId": "85dd7845-55b0-4b1d-9f1b-17a6f51c4dea",
     "W9Status": "OPENED",
     "StatusTs": "2021-02-22 04:24:09 -05:00",
     "TINMatching": null,
     "FormW9RequestType": "URL_API"
   }
 ],
 "Errors": null
}

Request 4 : Get W-9 status of a recipient with PayeeRef and no Requester (BusinessId or TIN) information.

FormW9/Status?PayeeRef=Pe123451234

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

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "Email": "steve@abcinc.com",
 "TotalRecords": 1,
 "Status": [
   {
     "SubmissionId": "85dd7845-55b0-4b1d-9f1b-17a6f51c4dea",
     "W9Status": "OPENED",
     "StatusTs": "2021-02-22 04:24:09 -05:00",
     "TINMatching": null,
     "FormW9RequestType": "URL_API"
   }
 ],
 "Errors": null
}

Request 5 : Get W-9 status of a recipient with invalid Email Address.

FormW9/Status?Email=steve@abcinccom

Response 5: Response will show the proper error message that the Email Id is invalid.

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": null,
 "Email": null,
 "TotalRecords": 0,
 "Status": null,
 "Errors": [
   {
     "Id": "F08-100022",
     "Name": "Email",
     "Message": "Invalid Email address."
   }
 ]
}

Request 6 : Get W-9 status of a recipient with PayeeRef [Where two recipients have the same Payee Reference].

FormW9/Status?PayeeRef=Pe123451234

Response 6: If two recipients have the same Payee Reference, the response will pull both the statuses as a list.

{
 "Requester": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "22-2222222"
 },
 "PayeeRef": "Pe123451234",
 "Email": null,
 "TotalRecords": 2,
 "Status": [
   {
     "SubmissionId": "85dd7845-55b0-4b1d-9f1b-17a6f51c4dea",
     "W9Status": "OPENED",
     "StatusTs": "2021-02-22 04:24:09 -05:00",
     "TINMatching": null,
     "FormW9RequestType": "URL_API"
   },
   {
     "SubmissionId": "65c6dc7a-c659-4f42-af26-bcd1ccf07432",
     "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-02-22 04:24:30 -05:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-06-10 07:16:01 -04:00",
       "Errors": null
     },
     "FormW9RequestType": "EMAIL_API"
   }
 ],
 "Errors": null
}

Extend your software with TaxBandits IRS E-file API Integration