Skip to main content
Version: 1.7.3


Webhooks are used to notify clients with the status of their recipient’s TIN Matching.

Go to Webhooks for information on Webhooks in TaxBandits.

Configure the Webhook for TIN Matching Status

  1. Log in to the developer console.

  2. Then navigate to Settings >> Webhooks.

  3. Click the Add Webhook button and choose the Event Type as TIN Matching Status Change while setting up your Webhook URL.

Webhook Settings

Add Webhook

  1. After entering the Callback URL, click on the Save button. Ensure that the callback URL is valid because the API will post a sample JSON. The callback URL is expected to return a HTTP 200 response code in order to remain active. If the API doesn’t return a 200 response code, then the callback URL will go inactive. You can retry posting the sample data to make the callback URL Active.

Response Body

SubmissionIdGuidUnique identifier of a submission.
RecordIdGuidUnique identifier of the record.
SequenceIdStringUnique record identifier set by the client.
RecipientIdStringUnique identifier of the recipient.
NameStringName of the recipient.
TINTypeStringTIN Type of the recipient.
TINStringTaxpayer Identification Number of the recipient.
StatusStringTIN Matching order status.
StatusTsStringTimestamp of the TIN Matching status.
NumOfAttemptsRmngStringNumber of TIN Matching attempts remaining for the TIN in TaxBandits.
ErrorsobjectShows detailed error information in the request.

Webhook Response for Success Status

"SubmissionId": "b870040d-fded-420b-b424-28bf0dd11261",
"RecordId": "5e2433ef-0d2e-4d8d-beba-06dac739a9fc",
"SequenceId": "A12343",
"RecipientId": "f871240d-fded-420b-b424-28bf0dd11261",
"Name": "John",
"TINType": "EIN",
"TIN": "12-1231234",
"Status": "SUCCESS",
"StatusTs": "2021-05-10 03:04:52 -04:00",
"NumOfAttemptsRmng": null,
"Errors": null

Webhook Response for Failed Status

"SubmissionId": "e26580d0-c533-48d1-b177-cce38d95b5c3",
"RecordId": "aa2f9641-74f1-49ec-8635-02576a8878df",
"SequenceId": "A12345",
"RecipientId": null,
"Name": "Steve Smith",
"TINType": "SSN",
"TIN": "121-23-7900",
"Status": "FAILED",
"StatusTs": "2021-05-06 21:27:05 -04:00",
"NumOfAttemptsRmng": 2,
"Errors": null