Status

Status

This endpoint can be used to retrieve the status of TIN Matching requests initiated in the TaxBandits API.

Available Statuses:

• Order Created – The TIN Matching request has been initiated, but is yet to be submitted for IRS verification.
• Under Process – The TIN Matching request is being processed in batches and is awaiting submission to the IRS.
• Sent to Agency – The TIN Matching request has been submitted to the IRS for verification.
• Success – The recipient's Name, TIN, and TINType combination match the IRS database.
• Failed – The recipient's Name, TIN, and TINType combination do not match the IRS database.
• Canceled – The TIN Matching request for recipients has been canceled.

GET TINMatchingRecipients/Status 

Run in Postman

Request Params

Field	Type	Description
RecipientTINType	String	TIN Type of the recipient. Allowed values: "SSN", "EIN", "ITIN"
RecipientTIN	String	Taxpayer Identification Number of the recipient. Size Range: 9-11(including hypen)
SubmissionId	Guid	Unique identifier of a submission.
RecordId	Guid	Unique identifier of the record.

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
Business	object	Object to identify the Business Details.
BusinessId	Guid	An unique identifier of the business.
TIN	String	Taxpayer Identification Number of the business.EIN for a company and SSN for an Individual.
PayerRef	string	An unique identifier for each payer completing their information. This identifier can be used in future references of the payer in the API.
RecordId	Guid	Unique identifier of the record.
SequenceId	String	Unique identifier for the record set by the client in the request.
RecipientId	String	Unique identifier of the recipient.
Name	String	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.
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

Request Params

Sample 1

Get the TIN Matching status of a recipient with SubmissionId and RecordId

TINMatchingRecipients/Status?SubmissionId=54d2226b-c8ae-43d1-9ed5-018250a25146&RecordId=7b82b242-1223-4029-9251-c0446298f620

Sample 2

Get the TIN Matching status of a recipient with Recipient TINType and Recipient TIN.

TINMatchingRecipients/Status?RecipientTINType=EIN&RecipientTIN=12-1231234

Sample 3

Get the TIN Matching status of a recipient with an invalid Recipient TIN.

TINMatchingRecipients/Status?RecipientTINType=EIN&RecipientTIN=12-123123

Response JSON

200

Success Response - This is a sample response for successful API requests.

{
  "SubmissionId": "46f10e28-6d61-4ea3-806b-d32b5dbdafa5",
  "Business": {
	"BusinessId": "a3b70845-669c-43ad-bdca-bfaeb4b3d7e4",
	"TIN": "14-5258330",
      "PayerRef": "Snow123"
  },
"RecordId": "384dfcb3-19b0-46e6-91f9-60a62d0e69b8",
  "SequenceId": "01",
  "RecipientId": "ac5baf44-4c89-4c22-a7c8-289fd6444232",
  "Name": "Snowdaze LLC",
  "TINType": "EIN",
  "TIN": "73-8744848",
  "Status": "SUCCESS",
  "StatusTs": "2025-11-14 08:20:10 -05:00",
  "NumOfAttemptsRmng": 2,
  "Errors": null
}

400

Bad Request Response - You'll get the below response when your API requests contain any validation errors.

{
  "SubmissionId": "00000000-0000-0000-0000-000000000000",
  "RecordId": "00000000-0000-0000-0000-000000000000",
  "SequenceId": null,
  "RecipientId": null,
  "Name": null,
  "TINType": null,
  "TIN": null,
  "Status": null,
  "StatusTs": null,
  "NumOfAttemptsRmng": null,
  "Errors": [
      {
          "Id": "F72-100013",
          "Name": "Request Invalid",
          "Message": "Either SubmissionId and recordId or TIN and TINType is Required"
      }
  ]
}

401

Unauthorized Response - You'll get the below response when your API requests don't contain valid authentication credentials.

{
  "StatusCode": 401,
  "StatusName": "Unauthorized",
  "StatusMessage": "Invalid authorization credentials",
  "Errors": [
      {
          "Id": "AUTH-100025",
          "Name": "Authorization",
          "Message": "Authorization should not be empty"
      }
  ]
}

404

{
  "SubmissionId": "3d9a54c1-c4e4-43df-92a8-bd46d4675524",
  "RecordId": "14baed85-e265-4316-9826-08dde42185e6",
  "SequenceId": null,
  "RecipientId": null,
  "Name": null,
  "TINType": null,
  "TIN": null,
  "Status": null,
  "StatusTs": null,
  "NumOfAttemptsRmng": null,
  "Errors": [
      {
          "Id": "F72-100012",
          "Name": "No Records",
          "Message": "No Records found for the given request"
      }
  ]
}