List

List

This endpoint can be used to retrieve the list of TIN Matching records initiated under a particular business or submission. You can filter the list based on the TIN Status and Date Range.

GET TINMatchingRecipients/List 

Run in Postman

Request Params

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.
PayerRef	string	Optional An unique identifier for each payer completing their information. This identifier can be used in future references of the payer in the API.
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. Note: PageSize can be maximum of 100.
FromDate	String	Optional List the TIN Matching records between the date range. Date format - MM/DD/YYYY
ToDate	String	Optional List the TIN Matching records between the date range. Date format - MM/DD/YYYY

Response Body

Field	Type	Description
Business	object	Business information.
BusinessId	Guid	Unique identifier of the business.
TIN	String	Taxpayer Identification Number of the business.
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.
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.
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

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

Sample 2

List with BusinessID.

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

Sample 3

List with SubmissionID.

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

Sample 4

List with TIN.

TINMatchingRecipients/List?TIN=124563758

Sample 5

List without BusinessID or TIN.

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

Response JSON

200

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

{
"Business": {
 "BusinessId": "387f41d7-b238-455b-b9d7-48f7d48889f5",
 "TIN": "22-2222222",
 "PayerRef": "Snow123",
},
"TINMatchingRecords": [
 {
   "SubmissionId": "220a8c29-a734-4a91-8b0e-bd9cc957503a",
   "RecordId": "c4653564-d6ad-47cc-99c8-9ef08d6029a6",
   "SequenceId": "Pe123451234",
   "RecipientId": "f871240d-fded-420b-b424-28bf0dd11261",
   "Name": "Snowdaze 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
}

400

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

{
  "Business": null,
  "TINMatchingRecords": null,
  "TotalRecords": 0,
  "TotalPages": 0,
  "Page": 0,
  "PageSize": 0,
  "Errors": [
      {
          "Id": "F68-100029",
          "Name": "SubmissionId",
          "Message": "SubmissionId is invalid"
      }
  ]
}

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