Request
This endpoint can be used to request initiate TIN Matching for a particular recipient.
POST InstantTINMatch/RequestRequest Body
| Field | Type | Description |
|---|---|---|
| RefId | string | Optional 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 |
| BusinessNm | string | If the TIN Type is EIN, provide the Name of the Business. Size Range: ..75 |
| FirstNm | string | If the TIN Type is SSN, provide the First Name of the Individual. Size Range: ..20 |
| MiddleNm | string | Optional If the TIN Type is SSN, provide the Middle Name of the Individual. Size Range: ..20 |
| LastNm | string | If the TIN Type is SSN, provide the Last Name of the Individual. Size Range: ..20 |
| TINType | string | Specify the TIN type of the recipient.Allowed values |
| TIN | string | Enter the nine-digit taxpayer identification number of the Recipient with or without hyphens (SSN or EIN). Size Range: 9-11 |
| IsSaveInAddBook | Boolean | If set as TRUE, the recipient will be added to the Address Book for future use, and a RecipientId will be generated. |
| AddBookDetails | object | Contains BusinessId and recipient address details. |
| BusinessId | Guid | Specify the business under which you want the recipient to be saved in the Address Book. |
| RecipientAddress | object | Provide the address of the recipient. |
| IsForeign | Boolean | If set as true, identifies the business address as a foreign address. |
| USAddress | Object | Optional Collects US address details of the recipient. |
| Address1 | string | Optional Recipient US Address 1 (street address or post office box of that locality). This will be pre-filled on the Form. Size Range: ..46 |
| Address2 | string | Optional Recipient US Address 2 (suite or apartment number). This will be pre-filled on the Form. Size Range: ..46 |
| City | string | Optional Recipient US City. This will be pre-filled on the Form. Size Range: ..50 |
| State | string | Optional Recipient US State Code. This will be pre-filled on the Form. Size Range: 2 Allowed values |
| ZipCd | string | Optional Recipient Zip Code. In the format 99999 or 99999-9999. This will be pre-filled on the Form. Size Range: 5..10 |
| ForeignAddress | object | Optional If IsForeign is true, pass the foreign address of the recipient |
| Address1 | string | Optional Recipient's foreign address (street address or post office box of that locality) Size Range: ..50 |
| Address2 | string | Optional Recipient's suite or apartment Size Range: ..50 |
| City | string | Optional Recipient's city. Size Range: ..50 |
| ProvinceOrStateNm | string | Optional Recipient's Province or State Name. Size Range: ..50 |
| Country | string | Optional Recipient's country code. Size Range: ..2 Allowed values |
| PostalCd | string | Optional 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
| Field | Type | Description |
|---|---|---|
| StatusCode | number | Returns the HTTP status codes like 200,300 etc. |
| StatusName | string | Name of the status code |
| StatusMessage | string | Detailed status message of the request. |
| RecordId | Guid | A 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. |
| RecipientId | Guid | A 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. |
| RefId | string | A unique identifier for each Instant TIN Matching request. |
| TINStatusCode | string | Status code of the TIN Match result. |
| TINStatus | string | TIN Matching status from the IRS. |
| TINStatusMsg | string | Detailed TIN matching status message given by the IRS. |
| Errors | object[] | Contains the detailed error information from the request, if any. |
| 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. |
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
}