Webhook

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.

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

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.

4. 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

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
RecordId	Guid	Unique identifier of the record.
SequenceId	String	Unique record identifier set by the client.
RecipientId	String	Unique identifier of the recipient.
Name	String	Name of the recipient.
TINType	String	TIN Type of the recipient.
TIN	String	Taxpayer Identification Number of the recipient.
Status	String	TIN Matching order status.
StatusTs	String	Timestamp of the TIN Matching status.
NumOfAttemptsRmng	String	Number of TIN Matching attempts remaining for the TIN in TaxBandits.
Errors	object	Shows 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
}