Skip to main content
Version: 1.7.3

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.

  1. 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).

  2. 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
Run in Postman

Request Body

FieldTypeDescription
TINMatchingDetailsobjectThe object contains the Business Information and the Recipients listed for TIN Matching.
    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)
    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"
        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

Request JSON

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

Response Body

FieldTypeDescription
SubmissionIdGuidUnique identifier of a submission.
BusinessIdGuidUnique identifier of the business.
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.

Response JSON

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