Skip to main content
Version: 1.7.3

Request

Request

This endpoint allows you to initiate TIN Matching for multiple recipients associated with the same business simultaneously. Your request JSON must include the details of the recipients along with the BusinessId of the payer associated with the recipients.

Note:

Once initiated, it may take up to 24 hours to complete the verification with the IRS.

How does this work?​

1. OAuth 2.0 Authentication​

To authenticate the request, you must first call the Auth method to get an access token. This token is required to be included in the request header as the Bearer token.

Refer to the OAuth 2.0 Authentication guide for details on JWT authentication and token handling.

2. Call the TINMatchingRecipients/Request endpoint​

The request must contain the following parameters:

  • Authorization Header – Include the Bearer token obtained from OAuth.

  • Recipient Details (as an array) – Include the Recipient Name, TIN Type, and TIN.If the recipient is already saved in the system, you can simply provide the RecipientId instead of the full recipient details.

  • Business Details (Optional) — You can send either the BusinessId or the TIN of the business associated with the recipients. If no business is specified, TaxBandits will link the recipients to the default business. To retrieve the BusinessId, refer to the Business endpoint.

2. TIN Matching Process​

TaxBandits will send the provided TIN matching requests to the IRS. Once the IRS has processed the TIN matching requests, TaxBandits will notify you via webhook (if you’ve configured for the event type TIN Matching Status Change.

The webhook payload will contain the following details for each recipient: Recipient Name, TIN, TIN Type, and TIN Matching Status. Learn more about webhooks.

POST TINMatchingRecipients/Request
Run in Postman

Request Body

FieldTypeDescription
TINMatchingDetailsobjectThe object contains the Business Information and the Recipients listed for TIN Matching.
WebhookRefGuidOptional A unique identifier of the Webhooks that TaxBandits generates against each Callback URL when adding it to the console site.
If you pass the WebhookRef in the request JSON, we will post the webhook response to the corresponding Callback URL. If you don't pass one, the webhook response will be posted to the default Callback URL.
    BusinessobjectOptional value to save the TIN requested recipients to a particular Business.
        BusinessIdGuidOptional An unique identifier of the business.
        TINStringOptional Taxpayer Identification Number of the business.EIN for a company and SSN for an Individual.
Size Range: 9-11(including hypen)
        PayerRefstringOptional An unique identifier for each payer completing their information. This identifier can be used in future references of the payer in the API.
Size Range: ..50
    Recipientsobject[]List recipient details as an array under this object.
        SequenceIdStringUse this Identifier to refer to a particular recipient. The same SequenceId will be returned in the response for your reference.
Size Range: 1-50
        RecipientIdGuidThe unique ID generated by TaxBandits once the recipient has completed his W-9 or in the response of recipient create endpoint.
        NameStringName of the recipient. Individual or Business Name.
Allowed values: "A-Z", "a-z", "-", "&"
Size Range: 1-40
        TINTypeStringTIN Type of the recipient.
Allowed values: "SSN", "EIN", "ITIN"
        TINStringTaxpayer Identification Number of the recipient.
Size Range: 9-11(including hypen)
        IsForeignBooleanWhen true, identifies the recipient address with a foreign address.
        USAddressobjectIf IsForeign is false, pass US address of the recipient
            Address1stringRecipient's US address (street address or post office box of that locality)
Size Range: ..46
            Address2stringOptional Recipient's suite or apartment
Size Range: ..46
            CitystringRecipient's city
Size Range: ..50
            StatestringRecipient'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"

            ZipCdstringRecipient's zip code.
Size Range: 5..10
        ForeignAddressobjectIf IsForeign is true, pass foreign address of the recipient
            Address1stringRecipient's foreign address (street address or post office box of that locality)
Size Range: ..50
            Address2stringOptional Recipient's suite or apartment
Size Range: ..50
            CitystringRecipient's city.
Size Range: ..50
            ProvinceOrStateNmstringRecipient's Province or State Name.
Size Range: ..50
            CountrystringRecipient's country code. Refer Static values.
Size Range: 2
Allowed values

"AF", "AX", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "AT", "AS", "AU", "AJ", "BF", "BA", "FQ", "BG", "BB", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "CA", "CV", "CJ", "CT", "CD", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "CS", "IV", "HR", "CU", "UC", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "EK", "ER", "EN", "ET", "FK", "FO", "FM", "FJ", "FI", "FR", "FP", "FS", "GB", "GA", "GG", "GM", "GH", "GI", "GR", "GL", "GJ", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "VT", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "KZ", "KE", "KQ", "KR", "KN", "KS", "KV", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MR", "MP", "MX", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "WA", "NR", "BQ", "NP", "NL", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "CQ", "NO", "MU", "OC", "PK", "PS", "LQ", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RO", "RS", "RW", "TB", "RN", "WS", "SM", "TP", "SA", "SG", "RI", "SE", "SL", "SN", "NN", "LO", "SI", "BP", "SO", "SF", "SX", "OD", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UK", "UY", "UZ", "NH", "VE", "VM", "VQ", "WQ", "WF", "WI", "YM", "ZA", "ZI"

            PostalCdstringRecipient's Postal Code.
Size Range: ..16

Response Body

FieldTypeDescription
SubmissionIdGuidUnique identifier of a submission.
BusinessIdGuidUnique identifier of the business.
PayerRefstringAn unique identifier for each payer completing their information. This identifier can be used in future references of the payer in the API.
TINMatchingRecordsobjectContains success and failed records.
    SuccessRecordsobject[]List of TIN Matching records successfully created.
        RecordIdGuidGenerated by TaxBandits to identify a particular record in future.
        SequenceIdStringUnique identifier for the record, set by the client in the request.
        RecipientIdGuidAn unique identifier generated by TaxBandits for a Recipient. You can use this id for your future reference to Update.
        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.
    ErrorRecordsobject[]List of TIN Matching error record.
        SequenceIdStringUnique identifier for the record, set by the client in the request.
        RecipientIdGuidAn unique identifier generated by TaxBandits for a Recipient. You can use this id for your future reference to Update.
        NameStringName of the recipient.
        TINTypeStringTIN Type of the recipient.
        TINStringTaxpayer Identification Number of the recipient.
        Errorsobject[]Array of errors for the recipient.
            IdstringError ID number. This ID is assigned by TaxBandits and it is unique for each error.
            NamestringName of the errored node.
            MessagestringShows the error message.
    ErrorsobjectCollection of error records in the request.
        IdstringError ID number. This ID is assigned by TaxBandits and it is unique for each error.
        NamestringName of the errored node.
        MessagestringShows the error message.

Request JSON​

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


{
"TINMatchingDetails": {
  "WebhookRef":"99db0874-e749-48d6-b96f-de6447d03667",
  "Business": {
    "BusinessId": "7b82b242-1223-4029-9251-c0446298f620",
    "TIN": null,
    "PayerRef": "Snow123"
  },
  "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"
      }
    }
  ]
}
}

Response JSON​

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

{
"SubmissionId": "54d2226b-c8ae-43d1-9ed5-018250a25146",
"BusinessId": "7b82b242-1223-4029-9251-c0446298f620",
"PayerRef": "Snow123",
"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": "2025-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": "2025-03-31 13:46:36 -04:00",
      "NumOfAttemptsRmng": 2
    }
  ],
  "ErrorRecords": null
},
"Errors": null
}