Skip to main content
Version: 1.7.3

Status

Status

Use this endpoint to retrieve the status of Form W-9 and W-8 requests associated with a specific recipient. The endpoint returns both completed and in-progress forms, allowing you to track the recipient's progress throughout the W-9/W-8 lifecycle.

Alternative Ways to Track Status

As an alternative to using this endpoint, you have the following options to stay updated on request statuses:

  • Configure webhooks for the event type 'WhCertificate Status Change Webhook'. Learn more
  • Enable web messaging for real-time status updates.
  • Enable the W-9/W-8 Request Status Digest in your Developer Console to receive periodic email summaries. Learn more

Key Points​

  • If multiple forms exist for the same recipient (PayeeRef), all associated statuses will be returned.
  • If a BusinessId is not provided, TaxBandits will return statuses for the matching recipient under your default business.
  • TIN Matching status is returned only for W-9 forms where TIN Matching is enabled.

W-9/W-8 status codes​

The following statuses indicate the status of a recipient's W-9 or W-8 request.

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.
ORDER_NOT_CREATED✅✅A TIN Matching request was not created since the provided TIN type is not applicable for TIN Matching.

TIN Matching status codes​

TIN Matching statuses are available only for Form W-9 requests where TIN Matching is enabled.

StatusDescription
ORDER_CREATEDTIN Matching order has been created but not yet submitted to the IRS.
SUCCESSRecipient's Name and TIN match IRS records.
FAILEDRecipient's Name and TIN do not match IRS records.
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
PhoneStringThe phone number of the recipient
Size Range: 4-16
CountryPhoneCodeStringRecipient’s country code. If not provided, the US will be selected by default.
Size Range: 2
Allowed values

"AF", "AX", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "AT", "AS", "AU", "AJ", "BF", "BA", "FQ", "BG", "BB", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "CA", "CV", "CJ", "CT", "CD", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "CS", "IV", "HR", "CU", "UC", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "EK", "ER", "EN", "ET", "FK", "FO", "FM", "FJ", "FI", "FR", "FP", "FS", "GB", "GA", "GG", "GM", "GH", "GI", "GR", "GL", "GJ", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "VT", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "KZ", "KE", "KQ", "KR", "KN", "KS", "KV", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MR", "MP", "MX", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "WA", "NR", "BQ", "NP", "NL", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "CQ", "NO", "MU", "OC", "PK", "PS", "LQ", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RO", "RS", "RW", "TB", "RN", "WS", "SM", "TP", "SA", "SG", "RI", "SE", "SL", "SN", "NN", "LO", "SI", "BP", "SO", "SF", "SX", "OD", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UK", "UY", "UZ", "NH", "VE", "VM", "VQ", "WQ", "WF", "WI", "YM", "ZA", "ZI"

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
Allowed values

"URL_GENERATED" ,"ORDER_CREATED" ,"SCHEDULED" ,"SENT" ,"OPENED" ,"COMPLETED" ,"AWAITING_TIN_CERTIFICATE" ,"COMPLETED_AND_TIN_MATCH_INPROGRESS" ,"INVALID" ,"BOUNCED" ,"ORDER_NOT_CREATED"

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​

Success Response - This is a sample response for successful API requests.

{
      "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": "2025-09-29 02:57:17 -04:00",
          "TINMatching": {
            "Status": "ORDER_CREATED",
            "StatusTs": "2025-09-29 03:30:14 -04:00",
            "Errors": null
          }
        }
      ],
    "Errors": null
      }