Skip to main content
Version: 1.7.3

Request

This endpoint can be used to request initiate TIN Matching for a particular recipient.

POST InstantTINMatch/Request

Request Body

FieldTypeDescription
RefIdstringOptional A unique identifier for each instant TIN Matching request. This identifier can be used in the future to get the status of the TIN Matching.
Size Range: ..50
BusinessNmstringIf the TIN Type is EIN, provide the Name of the Business.
Size Range: ..75
FirstNmstringIf the TIN Type is SSN, provide the First Name of the Individual.
Size Range: ..20
MiddleNmstringOptional If the TIN Type is SSN, provide the Middle Name of the Individual.
Size Range: ..20
LastNmstringIf the TIN Type is SSN, provide the Last Name of the Individual.
Size Range: ..20
TINTypestringSpecify the TIN type of the recipient.
Allowed values

"SSN", "EIN", "NA"

TINstringEnter the nine-digit taxpayer identification number of the Recipient with or without hyphens (SSN or EIN).
Size Range: 9-11
IsSaveInAddBookBooleanIf set as TRUE, the recipient will be added to the Address Book for future use, and a RecipientId will be generated.
AddBookDetailsobjectContains BusinessId and recipient address details.
   BusinessIdGuidSpecify the business under which you want the recipient to be saved in the Address Book.
   RecipientAddressobjectProvide the address of the recipient.
      IsForeignBooleanIf set as true, identifies the business address as a foreign address.
      USAddressObjectOptional Collects US address details of the recipient.
         Address1stringOptional Recipient US Address 1 (street address or post office box of that locality). This will be pre-filled on the Form.
Size Range: ..46
         Address2stringOptional Recipient US Address 2 (suite or apartment number). This will be pre-filled on the Form.
Size Range: ..46
         CitystringOptional Recipient US City. This will be pre-filled on the Form.
Size Range: ..50
         StatestringOptional Recipient US State Code. This will be pre-filled on the Form.
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"

         ZipCdstringOptional Recipient Zip Code. In the format 99999 or 99999-9999. This will be pre-filled on the Form.
Size Range: 5..10
      ForeignAddressobjectOptional If IsForeign is true, pass the foreign address of the recipient
         Address1stringOptional Recipient's foreign address (street address or post office box of that locality)
Size Range: ..50
         Address2stringOptional Recipient's suite or apartment
Size Range: ..50
         CitystringOptional Recipient's city.
Size Range: ..50
         ProvinceOrStateNmstringOptional Recipient's Province or State Name.
Size Range: ..50
         CountrystringOptional Recipient's country code.
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"

         PostalCdstringOptional Recipient's Postal Code.
Size Range: ..16

Request JSON

{
    "RefId": "Biz001",
    "BusinessNm": "Snowdaze LLC",
    "FirstNm": null,
    "MiddleNm": null,
    "LastNm": null,
    "TINType": "EIN",
    "IsForced": true,
    "TIN": "210811100",
    "IsSaveInAddBook": true,
    "AddBookDetails": {
        "BusinessId": "9f57ce20-2faa-48a0-a600-00a071c1d579",
        "RecipientAddress": {
            "IsForeign": false,
            "USAddress": {
                "Address1": "3576 AIRPORT WAY",
                "Address2": "UNIT 9",
                "City": "FAIRBANKS",
                "State": "AK",
                "ZipCd": "99709"
            },
            "ForeignAddress": {
                "Address1": "1425 10th Avenue",
                "Address2": "PO Box 4001",
                "City": "Victoria",
                "ProvinceOrStateNm": "Ontario",
                "Country": "CA",
                "PostalCd": "BC V8X 3X4"
            }
        }
    }
}

Response Body

FieldTypeDescription
StatusCodenumberReturns the HTTP status codes like 200,300 etc.
StatusNamestringName of the status code
StatusMessagestringDetailed status message of the request.
RecordIdGuidA unique identifier generated by TaxBandits when an Instant TIN Matching request is created. This can be used in the future to get the status of TIN Matching.
RecipientIdGuidA unique identifier is generated by TaxBandits for a recipient when an Instant TIN Matching request is created. This can be used for future reference to get the status of the recipient.
RefIdstringA unique identifier for each Instant TIN Matching request.
TINStatusCodestringStatus code of the TIN Match result.
TINStatusstringTIN Matching status from the IRS.
TINStatusMsgstringDetailed TIN matching status message given by the IRS.
Errorsobject[]Contains the detailed error information from the request, if any.
    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

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

{
    "StatusCode": 200,
    "StatusName": "Ok",
    "StatusMessage": "Successful API call",
    "RecordId": "a73f6045-b051-4ab1-af47-c91d3f080b79",
    "RecipientId": "42003b44-663c-41f5-88c4-f548a81bb5b9",
    "RefId": "Biz001",
    "TINStatusCode": "TIN-001",
    "TINStatus": "SUCCESS",
    "TINStatusMsg": "TIN and Name combination matches IRS records.",
    "Errors": null
}