Version: 1.7.3

List

Use this method to list the TIN Matching records under a particular business or submission. The TIN Matching records can be filtered based on the Status and Date Range.

GET TINMatchingRecipients/List

Request Body

Field	Type	Description
BusinessId	Guid	`Optional` A unique identifier of the business.
TIN	String	`Optional` Taxpayer Identification Number of the business. Supply TIN if you do not have the BusinessId. Size Range: 9-11(Including hyphen)
SubmissionId	Guid	`Optional` Unique identifier of a submission.
Status	String	TIN Matching order status. Allowed values: "ORDER_CREATED", "UNDER_PROCESS", "SENT_TO_AGENCY", "FAILED", "SUCCESS", "CANCELED", "ALL"
Page	int	`Optional` Page number that needs to be listed in the Response. If the value is not given, then the page will be defaulted to 1
PageSize	int	`Optional` Number of TIN Matching records to be listed in each page. If the value is not given, then the page size will be defaulted to 100.
FromDate	String	`Optional` List the TIN Matching records between the date range.
ToDate	String	`Optional` List the TIN Matching records between the date range.

Response Body

Field	Type	Description
Business	object	Business information.
BusinessId	Guid	Unique identifier of the business.
TIN	String	Taxpayer Identification Number of the business.
TINMatchingRecords	object	Array of TIN Matching records returned based on the conditions given in the request.
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.
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.
TotalRecords	Int	Total number of records returned in the response.
TotalPages	Int	Number of pages with the records.
Page	Int	Requested Page Number.
PageSize	Int	Requested Page Size.
Errors	Object	Shows detailed error information.

Request 1 : List with all valid parameters.

TINMatchingRecipients/List?BusinessId=387f41d7-b238-455b-b9d7-48f7d48889f5&TIN=124563758&SubmissionId=220a8c29-a734-4a91-8b0e-bd9cc957503a&Status=SUCCESS&Page=1&PageSize=10&FromDate=03/05/2020&ToDate=03/07/2020

Response 1

{
 "Business": {
   "BusinessId": "387f41d7-b238-455b-b9d7-48f7d48889f5",
   "TIN": "22-2222222"
 },
 "TINMatchingRecords": [
   {
     "SubmissionId": "220a8c29-a734-4a91-8b0e-bd9cc957503a",
     "RecordId": "c4653564-d6ad-47cc-99c8-9ef08d6029a6",
     "SequenceId": "Pe123451234",
     "RecipientId": "f871240d-fded-420b-b424-28bf0dd11261",
     "Name": "ABC LLC",
     "TINType": "EIN",
     "TIN": "12-1231234",
     "NumOfAttempts": null,
     "Status": "SUCCESS",
     "StatusTs": "2021-03-31 13:46:36 -04:00"
   },
   {
     "SubmissionId": "220a8c29-a734-4a91-8b0e-bd9cc957503a",
     "RecordId": "1aa8e8e0-11d4-4ec3-87d5-3f0747aaeb74",
     "SequenceId": "STS300",
     "RecipientId": "d5fe60f5-1eee-4d9a-a4e3-a58ea4bf8615",
     "Name": "Steve",
     "TINType": "SSN",
     "TIN": "222-2312-55",
     "NumOfAttempts": null,
     "Status": "SUCCESS",
     "StatusTs": "2021-03-31 13:46:36 -04:00"
   }
 ],
 "TotalRecords": 2,
 "TotalPages": 1,
 "Page": 1,
 "PageSize": 10,
 "Errors": null
}

Request 2 : List with BusinessID.

TINMatchingRecipients/List?BusinessId=387f41d7-b238-455b-b9d7-48f7d48889f5

Response 2

{
 "Business": {
   "BusinessId": "387f41d7-b238-455b-b9d7-48f7d48889f5",
   "TIN": "22-2222222"
 },
 "TINMatchingRecords": [
   {
     "SubmissionId": "54d2226b-c8ae-43d1-9ed5-018250a25146",
     "RecordId": "c4653564-d6ad-47cc-99c8-9ef08d6029a6",
     "SequenceId": "Pe123451234",     
     "RecipientId": "h871240d-fded-420b-b424-28bf0dd11261",
     "Name": "ABC LLC",
     "TINType": "EIN",
     "TIN": "12-1231234",
     "NumOfAttempts": null,
     "Status": "SUCCESS",
     "StatusTs": "2021-03-31 13:46:36 -04:00"
   },
   {
     "SubmissionId": "220a8c29-a734-4a91-8b0e-bd9cc957503a",
     "RecordId": "1aa8e8e0-11d4-4ec3-87d5-3f0747aaeb74",
     "SequenceId": "STS300",     
     "RecipientId": "04b367db-b945-4fd4-8269-db75a76186b3",
     "Name": "Steve",
     "TINType": "SSN",
     "TIN": "222-2312-55",
     "NumOfAttempts": null,
     "Status": "SUCCESS",
     "StatusTs": "2021-03-31 13:46:36 -04:00"
   }
 ],
 "TotalRecords": 2,
 "TotalPages": 1,
 "Page": 1,
 "PageSize": 10,
 "Errors": null
}

Request 3 : List with SubmissionID.

TINMatchingRecipients/List?SubmissionId=54d2226b-c8ae-43d1-9ed5-018250a25146

Response 3

{
 "Business": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "TIN": "22-2222222"
 },
 "TINMatchingRecords": [
   {
     "SubmissionId": "54d2226b-c8ae-43d1-9ed5-018250a25146",
     "RecordId": "c4653564-d6ad-47cc-99c8-9ef08d6029a6",
     "SequenceId": "Pe123451234",
     "RecipientId": "89f465fe-282a-4834-a613-2c9eedccaca4",
     "Name": "ABC LLC",
     "TINType": "EIN",
     "TIN": "12-1231234",
     "NumOfAttempts": null,
     "Status": "SUCCESS",
     "StatusTs": "2021-03-31 13:46:36 -04:00"
   },
   {
     "SubmissionId": "54d2226b-c8ae-43d1-9ed5-018250a25146",
     "RecordId": "1aa8e8e0-11d4-4ec3-87d5-3f0747aaeb74",
     "SequenceId": "STS300",
     "RecipientId": "f42e5de7-a88b-4421-a988-e1a03611c60d",
     "Name": "Steve",
     "TINType": "SSN",
     "TIN": "222-2312-55",
     "NumOfAttempts": null,
     "Status": "SUCCESS",
     "StatusTs": "2021-03-31 13:46:36 -04:00"
   }
 ],
 "TotalRecords": 2,
 "TotalPages": 1,
 "Page": 1,
 "PageSize": 10,
 "Errors": null
}

Request 4 : List with TIN.

TINMatchingRecipients/List?TIN=124563758

Response 4

{
 "Business": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "TIN": "12-4563758"
 },
 "TINMatchingRecords": [
   {
     "SubmissionId": "54d2226b-c8ae-43d1-9ed5-018250a25146",
     "RecordId": "c4653564-d6ad-47cc-99c8-9ef08d6029a6",
     "SequenceId": "Pe123451234",
     "RecipientId": "d7caf881-a577-4acb-8938-b0233eaa6ded",
     "Name": "ABC LLC",
     "TINType": "EIN",
     "TIN": "12-1231234",
     "NumOfAttempts": null,
     "Status": "SUCCESS",
     "StatusTs": "2021-03-31 13:46:36 -04:00"
   },
   {
     "SubmissionId": "220a8c29-a734-4a91-8b0e-bd9cc957503a",
     "RecordId": "1aa8e8e0-11d4-4ec3-87d5-3f0747aaeb74",
     "SequenceId": "STS300",
     "RecipientId": "8c8484f1-f685-4a2a-914d-931a15080329",
     "Name": "Steve",
     "TINType": "SSN",
     "TIN": "222-2312-55",
     "NumOfAttempts": null,
     "Status": "SUCCESS",
     "StatusTs": "2021-03-31 13:46:36 -04:00"
   }
 ],
 "TotalRecords": 2,
 "TotalPages": 1,
 "Page": 1,
 "PageSize": 10,
 "Errors": null
}

Request 5 : List without BusinessID or TIN.

TINMatchingRecipients/List?Status=SUCCESS&Page=1&PageSize=10&FromDate=03/05/2020&ToDate=03/07/2020

Response 5 : Because the Business Information was not given, the system will look up TIN Matching records under the default business and return the results.

{
 "Business": {
   "BusinessId": "7746f0cd-e8eb-4428-9240-12ea84160ee8",
   "TIN": "22-2222222"
 },
 "TINMatchingRecords": [
   {
     "SubmissionId": "54d2226b-c8ae-43d1-9ed5-018250a25146",
     "RecordId": "c4653564-d6ad-47cc-99c8-9ef08d6029a6",
     "SequenceId": "Pe123451234",
     "RecipientId": "903afb1f-1237-4fbe-b76a-e42e8d77d9f7",
     "Name": "ABC LLC",
     "TINType": "EIN",
     "TIN": "12-1231234",
     "NumOfAttempts": null,
     "Status": "SUCCESS",
     "StatusTs": "2021-03-31 13:46:36 -04:00"
   },
   {
     "SubmissionId": "220a8c29-a734-4a91-8b0e-bd9cc957503a",
     "RecordId": "1aa8e8e0-11d4-4ec3-87d5-3f0747aaeb74",
     "SequenceId": "STS300",
     "RecipientId": "61be6b8d-0602-42a7-80fb-016fb187520a",
     "Name": "Steve",
     "TINType": "SSN",
     "TIN": "222-2312-55",
     "NumOfAttempts": null,
     "Status": "SUCCESS",
     "StatusTs": "2021-03-31 13:46:36 -04:00"
   }
 ],
 "TotalRecords": 2,
 "TotalPages": 1,
 "Page": 1,
 "PageSize": 10,
 "Errors": null
}

Extend your software with TaxBandits IRS E-file API Integration