Skip to main content
Version: 1.7.3

Request

Request

This endpoint can be used to initiate instant TIN Matching for a particular recipient. Your request JSON must include the recipient details along with the BusinessId of the payer associated with that recipient.

Note:

Before you call this endpoint, please ensure that the Instant TIN Matching service has been enabled in your TaxBandits account. See how to enable

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 or ITIN, provide the First Name of the Individual.
Size Range: ..20
MiddleNmstringOptional If the TIN Type is SSN or ITIN, provide the Middle Name of the Individual.
Size Range: ..20
LastNmstringIf the TIN Type is SSN or ITIN, provide the Last Name of the Individual.
Size Range: ..20
IsForcedBooleanIf the RefId of a recipient, for whom an instant TIN matching request has already been initiated, is provided again, set IsForced to true.
This will bypass the system's duplicate check and allow the request to be processed again.
TINTypestringSpecify the TIN type of the recipient.
Allowed values

"SSN", "EIN", "ITIN"

TINstringEnter the nine-digit taxpayer identification number of the Recipient with or without hyphens (SSN or EIN or ITIN).
Size Range: 9-11
WebhookRefGuid
  • A unique identifier of the Webhook that TaxBandits generates against each Callback URL when adding it in 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.
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

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.

Request JSON​

{
    "RefId": "Biz001",
    "BusinessNm": "Snowdaze LLC",
    "FirstNm": null,
    "MiddleNm": null,
    "LastNm": null,
    "TINType": "EIN",
    "IsForced": true,
    "TIN": "210811100",
    "IsSaveInAddBook": true,
    "WebhookRef":"99db0874-e749-48d6-b96f-de6447d03667",
    "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 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
}