Extend your software with TaxBandits IRS E-file API Integration

Skip to main content
Version: 1.7.0

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

FieldTypeDescription
BusinessIdGuidOptional A unique identifier of the business.
TINStringOptional Taxpayer Identification Number of the business. Supply TIN if you do not have the BusinessId.
Size Range: 9-11(Including hyphen)
SubmissionIdGuidOptional Unique identifier of a submission.
StatusStringTIN Matching order status.
Allowed values: "ORDER_CREATED", "UNDER_PROCESS", "SENT_TO_AGENCY", "FAILED", "SUCCESS", "CANCELED", "ALL"
PageintOptional Page number that needs to be listed in the Response. If the value is not given, then the page will be defaulted to 1
PageSizeintOptional 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.
FromDateStringOptional List the TIN Matching records between the date range.
ToDateStringOptional List the TIN Matching records between the date range.

Response Body

FieldTypeDescription
BusinessobjectBusiness information.
    BusinessIdGuidUnique identifier of the business.
    TINStringTaxpayer Identification Number of the business.
TINMatchingRecordsobjectArray of TIN Matching records returned based on the conditions given in the request.
    SubmissionIdGuidUnique identifier of a submission.
    RecordIdGuidUnique identifier of the record.
    SequenceIdStringUnique record identifier set by the client.
    RecipientIdStringUnique identifier of 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.
TotalRecordsIntTotal number of records returned in the response.
TotalPagesIntNumber of pages with the records.
PageIntRequested Page Number.
PageSizeIntRequested Page Size.
ErrorsObjectShows 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
}