Skip to main content
Version: 1.7.3

Status

Status

Use this endpoint to retrieve the status of all Form W-9/W-8 requests (both complete and incomplete) associated with a specific recipient (payee).

Note: As an alternative to using this endpoint, you can configure webhooks for the event type 'WhCertificate Status Change Webhook'. You also have the option to enable web messaging for status updates.

Key Points​

  • If multiple forms exist for the same PayeeRef, all statuses will be returned as an array.
  • If no BusinessId is provided, the API will return the statuses for the recipient with a matching email or PayeeRef linked under your default business.

WHCertificate Statuses​

StatusApplies to RequestByEmailApplies to RequestByUrl /RequestByBusinessUrlDescription
URL_GENERATED✅✅The URL was generated, but the recipient hasn’t opened it yet.
ORDER_CREATED✅N/AThe request was created but has not yet been processed by TaxBandits.
SCHEDULED✅N/AThe email has been scheduled to be sent to the recipient.
SENT✅N/AW-9/W-8 form email has been sent to the recipient.
OPENED✅✅The recipient has opened the form link but has not completed it.
COMPLETED✅✅The recipient completed and signed the form
AWAITING_TIN_CERTIFICATE✅✅The recipient has completed and signed Form W-9 but has not provided their TIN.
COMPLETED_AND_TIN_MATCH_INPROGRESS✅✅Form completed, and TIN Matching is still processing.
INVALID✅✅TIN Matching failed; the form is now invalid.
BOUNCED✅N/AThe email could not be delivered. This may occur due to:
  • Invalid or non-existent email address - Delivery fails permanently. Update the recipient’s email to resend.
  • Full inbox or temporary issue - Delivery is retried automatically at equal intervals for up to 4 days.

TIN Matching Status Codes (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.
  • 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 the records in the IRS database.

Key Points​

GET WhCertificate/Status
Run in Postman

Request Params

FieldTypeDescription
PayeeRefStringA unique identifier for each recipient completing the Form W-9 and W-8 series.
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

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-8series.
    FormStatusStringStatus of the form.
    StatusTsStringTimestamp of the Form status.
    TINMatchingObjectTIN Matching information.
        StatusStringTIN Matching status.
        StatusTsStringTimestamp of the TIN Status.
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.

Request Params​

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

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

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
      }