Version: 1.6.1

Status

The status of a particular recipient’s W-9 or W-8BEN can be retrieved using this endpoint.

This method will return the status of all the FormWHCertificate requests (complete and incomplete) to a particular recipient.

WHCertificate Statuses
- URL_Generated - The WHCertificate (W-9/W-8BEN) URL is generated by TaxBandits, but the recipient has not opened it.
- Opened - The recipient has clicked the URL, opened the page and has yet to complete it.
- COMPLETED_AND_TIN_MATCH_INPROGRESS - Form W-9 has been completed and the TIN Matching process is inprogress. Applicable only if the recipient has completed Form W-9.
- Completed - Recipient has completed and signed the Form W-9/W-8BEN. If TIN Matching service is opted in the request and the recipient has completed W-9, then the completed status will be returned only when the TIN Matching status is Success for the Recipient.
- Invalid - TIN given by the recipient does not match with the IRS database and the W-9 is now invalid. You can request a new W-9 from the recipient. Applicable only if the recipient has completed Form W-9.

TIN Statuses (Applicable only for the recipients filling Form W-9)

* **Order_Created** - Recipient completed the Form W-9 and a TIN Matching order is created in Taxbandits. The TIN Matching request is yet to be sent to the IRS. 

* **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/W-8BENs for the same 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/W-8BEN that matches the Email or PayeeRef linked to the default business will be retrieved.

GET WhCertificate/Status

Request Body

Field	Type	Description
PayeeRef	String	A unique identifier for each recipient completing the Form W-9 and W-8BEN. 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 alternative for BusinessId. Size Range: 9-11 Allowed values: "EIN", "SSN"(Including hyphen)

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.
PayeeRef	String	Unique identifier of the recipient.
TotalRecords	int	Number of records available for the Payee Reference.
Status	Object[]	Statuses of the records for the recipient.
SubmissionId	Guid	Submission ID of the original Form Request.
FormType	String	Form Type. W-9 or W-8BEN.
FormStatus	String	Status of the form.
StatusTs	String	Timestamp of the Form status.
TINMatching	Object	TIN Matching information.
Status	String	TIN Matching status.
StatusTs	String	Timestamp of the TIN Status.
Errors	Object	Shows the detailed error message.
Errors	Object	Shows detailed error information of the API request.
ID	String	Error ID number. This ID is assigned by TaxBandits and it is unique for each error..
Name	String	Name of the errored node.
Message	String	Shows the error message.

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

WhCertificate/Status?PayeeRef=Pe123451234&BusinessId=1df66ad8-cb70-4b3f-9b9b-a216bd72814698F620

Response 1:

{
 "Requester": {
   "BusinessId": "1df66ad8-cb70-4b3f-9b9b-a216bd728146",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "XX-XXX2222"
 },
 "PayeeRef": "Pe123451234",
 "TotalRecords": 1,
 "Status": [
   {
     "SubmissionId": "23f02d75-cdb5-46d4-99c7-1395911a1c6d",
     "FormType": "FormW9",
     "FormStatus": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-09-29 02:57:17 -04:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-09-29 03:30:14 -04:00",
       "Errors": null
     }
   }
 ],
 "Errors": null
}

Request 2: Get W-9 status of a recipient with Payee Reference and BusinessId. This recipient was requested to complete W-9 multiple times using the same PayeeRef.

WhCertificate/Status?PayeeRef=Pe123451234&BusinessId=1df66ad8-cb70-4b3f-9b9b-a216bd728146

Response 2: Statuses of the W-9s are listed as an array.

{
 "Requester": {
   "BusinessId": "1df66ad8-cb70-4b3f-9b9b-a216bd728146",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "XX-XXX2222"
 },
 "PayeeRef": "Pe123451234",
 "TotalRecords": 3,
 "Status": [
   {
     "SubmissionId": "9107721a-5a8e-4869-8298-b6afaba9d3de",
     "FormType": null,
     "FormStatus": "URL_GENERATED",
     "StatusTs": "2021-09-29 04:23:18 -04:00",
     "TINMatching": null
   },
   {
     "SubmissionId": "68136ace-45f2-4db6-845d-3a89de821427",
     "FormType": "FormW9",
     "FormStatus": "OPENED",
     "StatusTs": "2021-09-29 04:23:15 -04:00",
     "TINMatching": null
   },
   {
     "SubmissionId": "23f02d75-cdb5-46d4-99c7-1395911a1c6d",
     "FormType": "FormW9",
     "FormStatus": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-09-29 02:57:17 -04:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-09-29 04:23:22 -04:00",
       "Errors": null
     }
   }
 ],
 "Errors": null
}

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

WhCertificate/Status?PayeeRef=Pe123451234&TIN=122222222

Response 3:

{
 "Requester": {
   "BusinessId": "1df66ad8-cb70-4b3f-9b9b-a216bd728146",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "XX-XXX2222"
 },
 "PayeeRef": "Pe123451234",
 "TotalRecords": 1,
 "Status": [
   {
     "SubmissionId": "23f02d75-cdb5-46d4-99c7-1395911a1c6d",
     "FormType": "FormW9",
     "FormStatus": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-09-29 02:57:17 -04:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-09-29 03:30:14 -04:00",
       "Errors": null
     }
   }
 ],
 "Errors": null
}

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

WhCertificate/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": "1df66ad8-cb70-4b3f-9b9b-a216bd728146",
   "BusinessNm": "John Enterprises",
   "TINType": "EIN",
   "TIN": "XX-XXX2222"
 },
 "PayeeRef": "Pe123451234",
 "TotalRecords": 1,
 "Status": [
   {
     "SubmissionId": "23f02d75-cdb5-46d4-99c7-1395911a1c6d",
     "FormType": "FormW9",
     "FormStatus": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
     "StatusTs": "2021-09-29 02:57:17 -04:00",
     "TINMatching": {
       "Status": "ORDER_CREATED",
       "StatusTs": "2021-09-29 03:30:14 -04:00",
       "Errors": null
     }
   }
 ],
 "Errors": null
}

Extend your software with TaxBandits IRS E-file API Integration