Webhook

As an alternative to using the 'Status' endpoint, you can configure a webhook to receive automated updates about the Instant TIN Matching status for recipients.

The payload will include important details such as the recipient’s name, TIN match status, and the timestamp of the update.

How to configure webhooks for Instant TIN Matching

1. Log in to the Developer Console:

   • Sandbox: sandbox.taxbandits.com
   • Live: console.taxbandits.com

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.

Note:

• Ensure your callback URL is valid and publicly accessible.

• Once saved, the API sends a sample JSON payload to your callback URL. Your server must respond with an HTTP status code 200 to keep the webhook active.

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

Request JSON with WebhookRef

Response Body

Field	Type	Description
RecordId	Guid	A unique identifier generated by TaxBandits when an Instant TIN Matching request is created.
WebhookRef	Guid	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.
RefId	string	A unique identifier for each Instant TIN Matching request.
TINStatusCode	string	Returns status code for the Instant TIN Matching request.
TINStatus	string	TIN Matching order status.
TINStatusMsg	string	Detailed TIN matching status message
Errors	object[]	An array of errors for the recipient.
Id	string	Error ID number. This ID is assigned by TaxBandits, and it is unique for each error.
Name	string	Name of the errored node.
Message	string	Shows 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."
}