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 Params

Field	Type	Description
RecipientTINType	String	TIN Type of the recipient. Allowed values: "SSN", "EIN"
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.

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 Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
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.

Response JSON

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
}

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
}

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"
    }
  ]
}