Skip to main content
Version: 1.7.0

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) for a particular recipient.

WHCertificate Statuses

  • URL_Generated - The WHCertificate (W-9/W-8BEN) URL has been generated by TaxBandits, but the recipient has not opened it.

  • Opened - The recipient has opened the URL and viewed the Form but is yet to complete it.

  • COMPLETED_AND_TIN_MATCH_INPROGRESS - Form W-9 has been completed, and the TIN Matching process is in progress. (Applicable only if the recipient has completed Form W-9)

  • Completed -The recipient has completed and signed the Form W-9/W-8BEN.

    • Note:If the TIN Matching service was 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 - The TIN given by the recipient does not match 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 - The 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 - The recipient’s Name and TIN combination match the records in the IRS database.
    • Failed - The recipient’s Name and TIN combination do 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 provide 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
Run in Postman

Request Params

FieldTypeDescription
PayeeRefStringA unique identifier for each recipient completing the Form W-9 and W-8BEN.
Size Range: 1-50
BusinessIdGuidOptional A Unique Business Identifier. If you do not supply the BusinessId in the request, the BusinessId of the default business will be mapped.
TINStringOptional Taxpayer Identification Number. Use this as an alternative for BusinessId.
Size Range: 9-11.
EmailStringEmail Address of the recipient.
Size Range: 1-100

Request Params

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

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

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.
PayeeRefStringA unique identifier of the recipient.
TotalRecordsintThe number of records available for the Payee Reference
StatusObject[]Statuses of the records for the recipient
    SubmissionIdGuidSubmission ID of the original Form Request
    FormTypeStringForm Type. W-9 or W-8BEN.
    FormStatusStringStatus of the form.
    StatusTsStringTimestamp of the Form status.
    TINMatchingObjectTIN Matching information.
        StatusStringTIN Matching status.
        StatusTsStringTimestamp of the TIN Status.
        ErrorsObjectShows the detailed error message.
ErrorsObject[]Shows detailed error information of the API request.
    IDStringError ID number assigned by TaxBandits and it is unique for each error.
    NameStringName of the errored node.
    MessageStringShows the error message.

Response JSON

The statuses for the given PayeeRef and BusinessId will be displayed.

{
        "Requester": {
          "BusinessId": "1df66ad8-cb70-4b3f-9b9b-a216bd728146",
          "BusinessNm": "Snowdaze LLC",
          "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
        }