Skip to main content
Version: 1.7.3

Status

Status

Use this endpoint to retrieve the status of Form W-9 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 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 'Form W-9 Status Change'. 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 status codes​

The following statuses indicate the status of a recipient's W-9 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 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 FormW9/Status
Run in Postman

Request Params

FieldTypeDescription
PayeeRefStringA unique identifier of a recipient. (Either PayeeRef or Email is required.)
Size Range: 1-50
EmailStringEmail Address of the recipient.
Size Range: 1-50
BusinessIdGuidOptional A unique identifier of a business. If you do not provide the BusinessId in the request, the BusinessId of the default business will be mapped.
TINStringOptional Taxpayer Identification Number. Use this as an alternate for BusinessId. (Values: EIN, SSN)
Size Range: 9-11

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
EmailStringThe email address of the recipient. (This is the email to which the W-9 request was sent)
TotalRecordsIntNumber of records available for the Payee Reference
StatusObject[]Statuses of the W-9 records for the recipient
SubmissionIdGuidSubmission ID of the original W-9 Request
DBAIdGuidUnique Identifier for the DBA.
DBARefGuidUnique identifier for each DBA. This identifier can be used in future references of the DBA in the API
W9StatusStringStatus of the W-9.
Allowed values

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

StatusTsStringTimestamp of the W-9 Status
TINMatchingObjectTIN Matching information.
StatusStringTIN Matching status.
StatusTsStringTimestamp of the TIN Matching Status.
ErrorsStringShows the detailed error message.
IdstringError ID number. This ID is assigned by TaxBandits and it is unique for each error.
NamestringName of the errored node.
MessagestringShows the error message
FormW9RequestTypeStringForm W-9 requested Type.
  • URL_API - Form W-9 was requested using the RequestByURL method.
  • Email_API - Form W-9 was requested using the RequestByEmail method.
ErrorsObject[]Detailed error information.
IdstringError ID number. This ID is 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.

FormW9/Status?PayeeRef=1746&BusinessId=5c0d6eb9-04b8-4e9d-9d54-fa30e8112b96

Response JSON​

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

{
  "Requester": {
      "BusinessId": "5c0d6eb9-04b8-4e9d-9d54-fa30e8112b96",
      "PayerRef": "12345",
      "BusinessNm": "Snowdaze LLC",
      "TINType": "EIN",
      "TIN": "20-1652598"
  },
  "PayeeRef": "1746",
  "Email": "john@sample.com",
  "TotalRecords": 1,
  "Status": [
      {
          "SubmissionId": "aaa29f83-805c-4b21-8ac1-8f4d4aa6292a",
          "DBAId": null,
          "DBARef": null,
          "W9Status": "COMPLETED_AND_TIN_MATCH_INPROGRESS",
          "StatusTs": "2024-04-12 06:22:34 -04:00",
          "TINMatching": {
              "Status": "ORDER_CREATED",
              "StatusTs": "2024-04-12 06:32:15 -04:00",
              "Errors": null
          },
          "FormW9RequestType": "URL_API"
      }
  ],
  "Errors": null
}