Skip to main content
Version: 1.7.3

Status

This endpoint will return the status of all the Form W-9s (complete and incomplete) for a particular recipient.

The statuses of the W-9s that were requested using the endpoints RequestByUrl, RequestByEmail, and TaxBandits UI can be retrieved using this endpoint.

W-9 Statuses:

  • URL Generated - The secure URL to complete W-9 has been generated by TaxBandits, but the recipient hasn’t opened it yet. (Not applicable to RequestByEmail method)
  • Order Created - The client has requested W-9 using the RequestByEmail method, and it is not processed by TaxBandits yet. (Not applicable to RequestByUrl method)
  • Scheduled - The TaxBandits email service has taken up the W-9 request, and the email is scheduled to be sent. (Not applicable to RequestByUrl method)
  • Sent - The email with the secure URL to complete the W-9 has been sent to the recipients. (Not applicable to RequestByUrl method)
  • Opened - The recipient has opened the URL and viewed the Form W-9 but has yet to complete it.
  • Completed - The recipient has completed and signed the Form W-9.
  • Completed_and_Tin_Match_InProgress - Form W-9 has been completed, and TIN Matching (if opted) is yet to be completed. TIN Matching is applicable only for completed Form W-9.
  • Invalid - The TIN given by the recipient doesn’t match the IRS database, and the W-9 has become invalid.

TIN Statuses:

  • Order Created - Recipient completed the Form W-9, and a TIN Matching order is created in TaxBandits.
  • 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 a 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 the records in the IRS database.

Key Points

  • If there are multiple W-9s for the same Email or 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 that matches the Email or PayeeRef linked to the default business will be retrieved.
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

Request Params

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

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

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

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
}