Extend your software with TaxBandits IRS E-file API Integration

Skip to main content
Version: 1.7.1

Status

This method will return the status of TIN Matching for a particular recipient.

TIN Matching Statuses:

  • Order Created - Client has created the TIN Matching order and it is yet to be sent to the IRS.
  • Under Process - Our system has batched the TIN Requests and is queued for IRS submission.
  • Sent to Agency - The order has been sent to the IRS for TIN verification.
  • Success - Recipient’s Name,TIN and TINType combination matches the IRS database.
  • Failed - Recipient’s Name,TIN and TINType combination does not match the IRS database.
  • Canceled - The TIN Matching request for a recipient was canceled by the client.
GET TINMatchingRecipients/Status

Request Body

FieldTypeDescription
RecipientTINTypeStringTIN Type of the recipient.
Allowed values: "SSN", "EIN"
RecipientTINStringTaxpayer Identification Number of the recipient.
Size Range: 9-11(including hypen)
SubmissionIdGuidUnique identifier of a submission.
RecordIdGuidUnique identifier of the record.

Response Body

FieldTypeDescription
SubmissionIdGuidUnique identifier of a submission.
RecordIdGuidUnique identifier of the record.
SequenceIdStringUnique identifier for the record set by the client in the request.
RecipientIdStringUnique identifier of the recipient.
NameStringof 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.

Request 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

Response 1

{
"SubmissionId": "54d2226b-c8ae-43d1-9ed5-018250a25146",
"RecordId": "7b82b242-1223-4029-9251-c0446298f620",
"SequenceId": "Pe123451234",
"RecipientId": "afdef206-fbfd-40eb-8675-e56733752c72",
"Name": "John",
"TINType": "EIN",
"TIN": "12-1231234",
"Status": "SENT_TO_AGENCY",
"StatusTs": "2021-03-31 13:46:36 -04:00",
"NumOfAttemptsRmng": 2,
"Errors": null
}

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

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

Response 2

{
"SubmissionId": "54d2226b-c8ae-43d1-9ed5-018250a25146",
"RecordId": "7b82b242-1223-4029-9251-c0446298f620",
"SequenceId": "Pe123451234",
"RecipientId": "894ae06e-6b98-47d6-a178-1c80fd547cb6",
"Name": "Steve Smith",
"TINType": "EIN",
"TIN": "12-1231234",
"Status": "SENT_TO_AGENCY",
"StatusTs": "2021-03-31 13:46:36 -04:00",
"NumOfAttemptsRmng": 2,
"Errors": null
}

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

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

Response 3

{
"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": "F08-100015",
"Name": "TIN",
"Message": "Invalid TIN"
}
]
}