Skip to main content
Version: 1.7.3

Status

Status

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

Form W9 Status Codes​

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​

  • 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.
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.
    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.
  • Email_UI - Form W-9 was requested from the TaxBandits UI application.
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​

The response will provide the status of W-9 for the specific Payee Reference and BusinessId.

{
  "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
}