TINMatchingRecipients

Payers filing 1099 forms can use our TIN Matching service to validate a recipient’s TIN, TINType and Name combination with the Internal Revenue Service (IRS).

The response to a TIN Matching request will be either correct or incorrect. When a TIN, TINType and the Name combination submitted is incorrect, you will not be informed about the right TIN.

TIN Matching services allow payers to confirm the Name and TIN details (Form W-9) provided by recipients prior to filing a 1099 for them. By selecting TIN Matching, payers can avoid filing corrections or paying potential penalties.

Key Points:

• The TIN MatchingRecipients endpoint can only be used to validate TINs of 1099 forms. If you want to validate employees TINs to file W-2s, use our other endpoint TINMatchingEmployees.

• The IRS takes a day to process the TIN Matching requests and provide results. Similarly the TIN Matching request submitted in TaxBandits will take at-least one day to get the result.

• To prevent phishing, TaxBandits allows 3 TIN requests for the same TIN and TINType with various names. After 3 attempts, our system will not allow any TIN Matching request for the same TIN and TINType.

Cancel

Use this method to cancel a particular request or submission. You can only cancel a request if the TIN Matching status is “Order Created”.

PUT TINMatchingRecipients/Cancel

Request Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
RecordIds	Guid[]	Optional Unique identifier of the record. Mention the multiple RecordIds, if you want to cancel multiple TIN Matching requests under a submission. Do not mention the record Ids if all the records under the submission need to be cancelled.

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
TINMatchingDetails	object	Collection of TIN Matching records requested to cancel.
SuccessRecords	object[]	Successfully canceled records.
SequenceId	String	Unique record identifier set by the client.
RecordId	Guid	Unique identifier of the record.
Status	String	TIN Matching order status.
StatusTs	String	Timestamp of the TIN Matching status.
ErrorRecords	object	Error records that were not canceled.
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.
Errors	object[]	Collection of error records in the request.
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.

Sample Request 1 : Cancel with SubmissionId and RecorIds

TINMatchingRecipients/Cancel?SubmissionId=387f41d7-b238-455b-b9d7-48f7d48889f5&RecordIds=15c3caa6-8402-4548-8713-4fcdd2f7d42d,eb39714e-f653-4c4d-a53c-07f24f9a9dj5

Sample Response 1

{
  "SubmissionId": "9d71ae45-df5f-49f7-86f8-e88f54132fa1",
  "TINMatchingDetails": {
      "SuccessRecords": [
          {
              "SequenceId": "1",
              "RecordId": "15c3caa6-8402-4548-8713-4fcdd2f7d42d",
              "Status": "CANCELED",
              "StatusTs": "2019-08-05 06:26:16 -04:00"
          },
          {
              "SequenceId": "2",
              "RecordId": "eb39714e-f653-4c4d-a53c-07f24f9a9dj5",
              "Status": "CANCELED",
              "StatusTs": "2019-08-05 06:26:16 -04:00"
          }
      ],
      "ErrorRecords": null
  },
  "Errors": null
}

Sample Request 2 : Cancel with SubmissionId.

TINMatchingRecipients/Cancel?SubmissionId=387f41d7-b238-455b-b9d7-48f7d48889f5

Sample Response 2

{
  "SubmissionId": "9d71ae45-df5f-49f7-86f8-e88f54132fa1",
  "TINMatchingDetails": {
      "SuccessRecords": [
          {
              "SequenceId": "1",
              "RecordId": "15c3caa6-8402-4548-8713-4fcdd2f7d42d",
              "Status": "CANCELED",
              "StatusTs": "2019-08-05 06:26:16 -04:00"
          },
          {
              "SequenceId": "2",
              "RecordId": "eb39714e-f653-4c4d-a53c-07f24f9a9dj5",
              "Status": "CANCELED",
              "StatusTs": "2019-08-05 06:26:16 -04:00"
          }
      ],
      "ErrorRecords": null
  },
  "Errors": null
}

Sample Request 3 : Cancel with invalid SubmissionId.

TINMatchingRecipients/Cancel?SubmissionId=447f41d7-b238-455b-b9d7-48f7d48889f5

Sample Response 3

{
   "SubmissionId": "00000000-0000-0000-0000-000000000000",
   "TinMatchingDetails": null,
   "Errors": [
       {
           "Id": "F68-100023",
           "Name": "SubmissionId",
           "Message": "SubmissionId is invalid"
       }
   ]
}

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.

Sample 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

Sample 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
}

Sample Request 2 : List with BusinessID.

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

Sample 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
}

Sample Request 3 : List with SubmissionID.

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

Sample 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
}

Sample Request 4 : List with TIN.

TINMatchingRecipients/List?TIN=124563758

Sample 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
}

Sample Request 5 : List without BusinessID or TIN.

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

Sample 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
}

Request

Use this endpoint to send TIN Matching requests to TaxBandits. You can send multiple TINMatching requests in a single submission.

How does this work?

1. Like any other TaxBandits API Endpoint, the first step is to call the Auth method to get the access token. This access token must be supplied in the request header as the ‘Bearer‘ token.
   

Refer to the OAuth 2.0 Authentication for more information on JWT authentication and how to integrate with the subsequent requests.

2. The second step is to call the TINMatchingRecipients/Request API endpoint with the following values:

   • Access Token in the header as Bearer Token (Generated using TaxBandits OAuth authentication API).

   • Business Details (BusinessId or TIN. Optional value to save the TIN requested recipients to a particular Business).
     Refer to the Business endpoint to learn more about creating a Business in TaxBandits and retrieving the Business Id. In TaxBandits, you can uniquely identify a business using either its TIN or the TBS generated Business Id. You can also define a ‘Default Business’ in the TaxBandits Application and skip sending the Business Identifier along with the request.

   • Recipient Details as an array (Recipient Name, TINType and TIN).

3. TaxBandits will send the TIN Matching requests to the IRS and get the statuses. Later, the client will be notified via Webhook. The Webhook payload will have the TIN Matching data such as the Name, TIN,TINType and Status of TIN Matching.

Refer to the TIN Matching webhook to learn more about webhook set up and sample payload.

POST TINMatchingRecipients/Request

Request Body

Field	Type	Description
TINMatchingDetails	object	The object contains the Business Information and the Recipients listed for TIN Matching.
Business	object	Optional value to save the TIN requested recipients to a particular Business.
BusinessId	Guid	Optional An unique identifier of the business.
TIN	String	Optional Taxpayer Identification Number of the business.EIN for a company and SSN for an Individual. Size Range: 9-11(including hypen)
Recipients	object[]	List recipient details as an array under this object.
SequenceId	String	Use this Identifier to refer to a particular recipient. The same SequenceId will be returned in the response for your reference. Size Range: 1-50
RecipientId	Guid	An unique ID generated by TaxBandits after the return is created and will be returned in the Response. You can use this id for your future reference to update.
Name	String	Name of the recipient. Individual or Business Name. Allowed values: "A-Z", "a-z", "-", "&" Size Range: 1-40
TINType	String	TIN Type of the recipient. Allowed values: "SSN", "EIN"
TIN	String	Taxpayer Identification Number of the recipient. Size Range: 9-11(including hypen)
IsForeign	Boolean	When true, identifies the recipient address with a foreign address.
USAddress	object	If IsForeign is false, pass US address of the recipient
Address1	string	Recipient's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	Optional Recipient's suite or apartment Size Range: ..35
City	string	Recipient's city Size Range: ..27
State	string	Recipient's state code. Refer Static values. Size Range: 2 Allowed values: "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP"
ZipCd	string	Recipient's zip code
ForeignAddress	object	If IsForeign is true, pass foreign address of the recipient
Address1	string	Recipient's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	Optional Recipient's suite or apartment Size Range: ..35
City	string	Recipient's city. Size Range: ..27
ProvinceOrStateNm	string	Recipient's Province or State Name. Size Range: ..30
Country	string	Recipient's country code. Refer Static values. Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Recipient's Postal Code

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
BusinessId	Guid	Unique identifier of the business.
TINMatchingRecords	object	Contains success and failed records.
SuccessRecords	object[]	List of TIN Matching records successfully created.
RecordId	Guid	Generated by TaxBandits to identify a particular record in future.
SequenceId	String	Unique identifier for the record, set by the client in the request.
RecipientId	Guid	An unique identifier generated by TaxBandits for a Recipient. You can use this id for your future reference to Update.
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.
ErrorRecords	object[]	List of TIN Matching error record.
SequenceId	String	Unique identifier for the record, set by the client in the request.
RecipientId	Guid	An unique identifier generated by TaxBandits for a Recipient. You can use this id for your future reference to Update.
Name	String	Name of the recipient.
TINType	String	TIN Type of the recipient.
TIN	String	Taxpayer Identification Number of the recipient.
Errors	object[]	Array of errors for the recipient.
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.
Errors	object	Collection of error records in the request.
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.

Sample Request 1 : Send TIN Matching requests by giving the BusinessId (Business) and recipient's information.

{
  "TINMatchingDetails": {
    "Business": {
      "BusinessId": "7b82b242-1223-4029-9251-c0446298f620",
      "TIN": null
    },
    "Recipients": [
      {
        "SequenceId": null,
        "RecipientId": "6j92b242-1223-4029-9251-c0446298j324",
        "Name": "Span LLC",
        "TINType": "EIN",
        "TIN": "12-1231234",
        "IsForeign": true,
        "USAddress": {
          "Address1": null,
          "Address2": null,
          "City": null,
          "State": null,
          "ZipCd": null
        },
        "ForeignAddress": {
          "Address1": "22 St",
          "Address2": "Clair Ave E",
          "City": "Toronto",
          "ProvinceOrStateNm": "Ontario",
          "Country": "CA",
          "PostalCd": "M1R 0E9"
        }
      },
      {
        "SequenceId": "STS078",
        "RecipientId": "7b92b242-1223-4029-9251-c0446298j324",
        "Name": "Steve Smith",
        "TINType": "SSN",
        "TIN": "121-23-1234",
        "IsForeign": true,
        "USAddress": {
          "Address1": null,
          "Address2": null,
          "City": null,
          "State": null,
          "ZipCd": null
        },
        "ForeignAddress": {
          "Address1": "22 St",
          "Address2": "Clair Ave E",
          "City": "Toronto",
          "ProvinceOrStateNm": "Ontario",
          "Country": "CA",
          "PostalCd": "M1R 0E9"
        }
      }
    ]
  }
}

Sample Response 1

{
  "SubmissionId": "54d2226b-c8ae-43d1-9ed5-018250a25146",
  "BusinessId": "7b82b242-1223-4029-9251-c0446298f620",
  "TINMatchingRecords": {
    "SuccessRecords": [
      {
        "RecordId": "1b23b562-9874-2547-6245-c654782f234",
        "SequenceId": "Pe123451234",
        "RecipientId": "6j92b242-1223-4029-9251-c0446298j324",
        "TINType": "EIN",
        "TIN": "12-1231234",
        "Status": "ORDER_CREATED",
        "StatusTs": "2021-03-31 13:46:36 -04:00",
        "NumOfAttemptsRmng": 2
      },
      {
        "RecordId": "2b33b562-9874-2547-6245-c654782f234",
        "SequenceId": "Pe123451235",
        "RecipientId": "7b92b242-1223-4029-9251-c0446298j324",
        "TINType": "SSN",
        "TIN": "121-23-1234",
        "Status": "ORDER_CREATED",
        "StatusTs": "2021-03-31 13:46:36 -04:00",
        "NumOfAttemptsRmng": 2
      }
    ]
  }
}

Sample Request 2 : Send TIN Matching requests by giving the Business TIN (Business) and recipients’ information.

{
  "TINMatchingDetails": {
    "Business": {
      "BusinessId": null,
      "TIN": "11-1111111"
    },
    "Recipients": [
      {
        "SequenceId": null,
        "RecipientId": "98u2b242-1223-4029-9251-c0446298j324",
        "Name": "Span LLC",
        "TINType": "EIN",
        "TIN": "12-1231234",
        "IsForeign": true,
        "USAddress": {
          "Address1": null,
          "Address2": null,
          "City": null,
          "State": null,
          "ZipCd": null
        },
        "ForeignAddress": {
          "Address1": "22 St",
          "Address2": "Clair Ave E",
          "City": "Toronto",
          "ProvinceOrStateNm": "Ontario",
          "Country": "CA",
          "PostalCd": "M1R 0E9"
        }
      },
      {
        "SequenceId": "STS078",
        "RecipientId": "7p92b242-1223-4029-9251-c0446298j324",
        "Name": "Steve Smith",
        "TINType": "SSN",
        "TIN": "121-23-1234",
        "IsForeign": true,
        "USAddress": {
          "Address1": null,
          "Address2": null,
          "City": null,
          "State": null,
          "ZipCd": null
        },
        "ForeignAddress": {
          "Address1": "22 St",
          "Address2": "Clair Ave E",
          "City": "Toronto",
          "ProvinceOrStateNm": "Ontario",
          "Country": "CA",
          "PostalCd": "M1R 0E9"
        }
      }
    ]
  }
}

Sample Response 2

{
  "SubmissionId": "54d2226b-c8ae-43d1-9ed5-018250a25146",
  "BusinessId": "7b82b242-1223-4029-9251-c0446298f620",
  "TINMatchingRecords": {
    "SuccessRecords": [
      {
        "RecordId": "1b23b562-9874-2547-6245-c654782f234",
        "SequenceId": "Pe123451234",
        "RecipientId": "98u2b242-1223-4029-9251-c0446298j324",
        "TINType": "EIN",
        "TIN": "12-1231234",
        "Status": "ORDER_CREATED",
        "StatusTs": "2021-03-31 13:46:36 -04:00",
        "NumOfAttemptsRmng": 2
      },
      {
        "RecordId": "2b33b562-9874-2547-6245-c654782f234",
        "SequenceId": "Pe123451235",
        "RecipientId": "7p92b242-1223-4029-9251-c0446298j324",
        "TINType": "SSN",
        "TIN": "121-23-1234",
        "Status": "ORDER_CREATED",
        "StatusTs": "2021-03-31 13:46:36 -04:00",
        "NumOfAttemptsRmng": 2
      }
    ]
  }
}

Sample Request 3 : Send TIN Matching requests without Business information (BusinessId or TIN). The recipients will be tied to the default business.

{
 "TINMatchingDetails": {
   "Business": null,
   "Recipients": [
     {
       "SequenceId": null,
       "RecipientId": "8ut2b242-1223-4029-9251-c0446298j324",
       "Name": "Span LLC",
       "TINType": "EIN",
       "TIN": "12-1231234",
       "IsForeign": true,
        "USAddress": {
          "Address1": null,
          "Address2": null,
          "City": null,
          "State": null,
          "ZipCd": null
        },
        "ForeignAddress": {
          "Address1": "22 St",
          "Address2": "Clair Ave E",
          "City": "Toronto",
          "ProvinceOrStateNm": "Ontario",
          "Country": "CA",
          "PostalCd": "M1R 0E9"
        }
     },
     {
       "SequenceId": "STS078",
       "RecipientId": "7yt92b242-1223-4029-9251-c0446298j324",
       "Name": "Steve Smith",
       "TINType": "SSN",
       "TIN": "121-23-1234",
       "IsForeign": true,
        "USAddress": {
          "Address1": null,
          "Address2": null,
          "City": null,
          "State": null,
          "ZipCd": null
        },
        "ForeignAddress": {
          "Address1": "22 St",
          "Address2": "Clair Ave E",
          "City": "Toronto",
          "ProvinceOrStateNm": "Ontario",
          "Country": "CA",
          "PostalCd": "M1R 0E9"
        }
     }
   ]
 }
}

Sample Response 3

{
  "SubmissionId": "54d2226b-c8ae-43d1-9ed5-018250a25146",
  "BusinessId": "7b82b242-1223-4029-9251-c0446298f620",
  "TINMatchingRecords": {
    "SuccessRecords": [
      {
        "RecordId": "1b23b562-9874-2547-6245-c654782f234",
        "SequenceId": "Pe123451234",
        "RecipientId": "8ut2b242-1223-4029-9251-c0446298j324",
        "TINType": "EIN",
        "TIN": "12-1231234",
        "Status": "ORDER_CREATED",
        "StatusTs": "2021-03-31 13:46:36 -04:00",
        "NumOfAttemptsRmng": 2
      },
      {
        "RecordId": "2b33b562-9874-2547-6245-c654782f234",
        "SequenceId": "Pe123451235",
        "RecipientId": "7yt92b242-1223-4029-9251-c0446298j324",
        "TINType": "SSN",
        "TIN": "121-23-1234",
        "Status": "ORDER_CREATED",
        "StatusTs": "2021-03-31 13:46:36 -04:00",
        "NumOfAttemptsRmng": 2
      }
    ]
  }
}

Sample Request 4 : TIN Matching request with an invalid Recipient TIN Type.

{
  "TINMatchingDetails": {
    "Business": {
      "TINType": null,
      "TIN": "11-1111111"
    },
    "Recipients": [
      {
        "SequenceId": "2d2b6e64-e4af-4474-8c2f-96fa0952abdv",
        "RecipientId": "9qb2b242-1223-4029-9251-c0446298j324",
        "Name": "Express LLC",
        "TINType": "EINs",
        "TIN": "12-1277473",
        "IsForeign": true,
        "USAddress": {
          "Address1": null,
          "Address2": null,
          "City": null,
          "State": null,
          "ZipCd": null
        },
        "ForeignAddress": {
          "Address1": "22 St",
          "Address2": "Clair Ave E",
          "City": "Toronto",
          "ProvinceOrStateNm": "Ontario",
          "Country": "CA",
          "PostalCd": "M1R 0E9"
        }
      }
    ]
  }
}

Sample Response 4 : The order is not created and the invalid Recipient TIN Type error is returned

{
  "SubmissionId": "00000000-0000-0000-0000-000000000000",
  "BusinessId": "2d2b6e64-e4af-4474-8c2f-96fa0952abda",
  "TINMatchingRecords": {
    "SuccessRecords": null,
    "ErrorRecords": [
      {
        "SequenceId": "2d2b6e64-e4af-4474",
        "RecipientId": "9qb2b242-1223-4029-9251-c0446298j324",
        "Name": "Express LLC",
        "TINType": "EINs",
        "TIN": "121-27-7473",
        "Errors": [
          {
            "Id": "F00-100234",
            "Name": "Recipient.TINType",
            "Message": "TIN Type is invalid"
          }
        ]
      }
    ]
  },
  "Errors": null
}

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

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.

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.

Sample 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

Sample 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
}

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

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

Sample 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
}

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

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

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

Webhook Responses

Webhooks are used to notify clients with the status of their recipient’s TIN Matching.

Go to Webhooks for information on Webhooks in TaxBandits.

Configure the Webhook for TIN Matching Status

1. Log in to the developer console.

   • Sandbox Console URL: sandbox.taxbandits.com (opens new window)
   • Live Console URL: console.taxbandits.com (opens new window)

2. Then navigate to Settings >> Webhooks.

3. Click the Add Webhook button and choose the Event Type as TIN Matching Status Change while setting up your Webhook URL.

4. After entering the Callback URL, click on the Submit button. Ensure that the callback URL is valid because the API will post a sample JSON. The callback URL is expected to return a HTTP 200 response code in order to remain active. If the API doesn’t return a 200 response code, then the callback URL will go inactive. You can retry posting the sample data to make the callback URL Active.

Response Body

Field	Type	Description
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.
Name	String	Name 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.

Sample Webhook Response for Success Status

{
 "SubmissionId": "b870040d-fded-420b-b424-28bf0dd11261",
 "RecordId": "5e2433ef-0d2e-4d8d-beba-06dac739a9fc",
 "SequeceId": "A12343",
 "RecipientId": "f871240d-fded-420b-b424-28bf0dd11261",
 "Name": "John",
 "TINType": "EIN",
 "TIN": "12-1231234",
 "Status": "SUCCESS",
 "StatusTs": "2021-05-10 03:04:52 -04:00",
 "NumOfAttemptsRmng": null,
 "Errors": null
}

Sample Webhook Response for Failed Status

{
 "SubmissionId": "e26580d0-c533-48d1-b177-cce38d95b5c3",
 "RecordId": "aa2f9641-74f1-49ec-8635-02576a8878df",
 "SequeceId": "A12345",
 "RecipientId": null,
 "Name": "Steve Smith",
 "TINType": "SSN",
 "TIN": "121-23-7900",
 "Status": "FAILED",
 "StatusTs": "2021-05-06 21:27:05 -04:00",
 "NumOfAttemptsRmng": 2,
 "Errors": null
}