Skip to main content
Version: 1.7.3

Webhook

Webhooks notify your system whenever there is a status update on a recipient’s instant TIN Matching request. The webhook payload includes key data such as the recipient’s name, TIN match status, and timestamp.

How to configure webhooks for Instant TIN Matching​

  1. Log in to the Developer Console:

  2. Navigate to Settings → Webhooks.

  3. Click 'Add Webhook'. Choose the event type as 'Instant TIN Matching Status Change'.

  4. Enter your Callback URL where you want to receive notifications and click Save. For Instant TIN Matching, you can add up to 5 Webhook URLs and choose the Callback URL to which the Webhook response needs to be posted.

  • Ensure your callback URL is valid and publicly accessible. Upon saving, the API sends a sample JSON payload to your callback URL.

  • Your server must respond with HTTP status code 200 to keep the webhook active.

  • If your callback URL does not return HTTP 200, the webhook will become inactive. You can retry posting sample data to reactivate it.

Request JSON with WebhookRef

Sample Json

Response Body

FieldTypeDescription
RecordIdGuidA unique identifier generated by TaxBandits when an Instant TIN Matching request is created.
WebhookRefGuid
  • A unique identifier of the Webhook that TaxBandits generates against each Callback URL when adding it in the console site.
  • If you pass the WebhookRef in the request JSON, we will post the webhook response to the corresponding Callback URL. If you don't pass one, the webhook response will be posted to the default Callback URL.
RefIdstringA unique identifier for each Instant TIN Matching request.
TINStatusCodestringReturns status code for the Instant TIN Matching request.
TINStatusstringTIN Matching order status.
TINStatusMsgstringDetailed TIN matching status message
Errorsobject[]An array of errors for the recipient.
    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

{
  "RecordId": "0d34e1bf-1765-4e57-88d9-7147b61470a9",
  "WebhookRef": "1bccb2e5-a57c-4786-9ff2-ad573b5f9d0d",
  "RefId": null,
  "TINStatusCode": "TIN-001",
  "TINStatus": "SUCCESS",
  "TINStatusMsg": "TIN and Name combination matches IRS records."
}