Submit TIN and name match asynchronous requests.
You can submit a TIN check by passing a Business Name or an Individual name along with their EIN or SSN. This is an asynchronous API call that returns a request id in the response. Use the GET-by-ID endpoint with that id to retrieve the final result. See How API Works for the asynchronous API lifecycle.
Only these body keys are accepted: tin, name, webhook_urls. Any other keys are ignored.
{
"tin": "string",
"name": "string",
"webhook_urls": ["string"]
}{
"name": "abc def",
"tin": "456456456"
}{
"name": "def ghi",
"tin": "456456456",
"webhook_urls": ["https://example.com/webhook", "https://example2.com/webhook"]
}{
"id": 6124075,
"name": "abc def",
"tin": "456456456",
"status": "Pending",
"created_by": "[email protected]",
"irs_code": -1,
"irs_reason": "",
"irs_service_status": "RUNNING",
"last_irs_check_date": "",
"created_date": "2025-06-03T11:39:03Z",
"updated_date": "2025-06-03T11:39:03Z"
}Request Parameters:
| Field Name | Field Type | Mandatory/Optional | Description |
|---|---|---|---|
| tin | String | Mandatory | 9 digits. Must pass TIN format validation. |
| name | String | Mandatory | Max 40 characters. Allowed characters: a-z, A-Z, 0-9, space, &, -. |
| webhook_urls | List of String | Optional | Up to 3 valid webhook endpoints. When the result is available, Compliancely POSTs to these URLs. Read more on Webhooks |
Response Parameters:
| Field Name | Field Type | Description |
|---|---|---|
| id | Integer | Request id for later GET-by-ID lookup |
| name | String | Submitted name |
| tin | String | Submitted TIN |
| status | String | Pending / TIN Matched / Did Not Match / In Review |
| created_by | String | Username of the authenticated requester |
| irs_code | Integer | IRS codes 0-8; Compliancely also uses -1 and 10 |
| irs_reason | String | Reason text for irs_code |
| irs_service_status | String | RUNNING or THE IRS TIN MATCHING SERVICE IS SLOW OR CURRENTLY EXPERIENCING AN OUTAGE |
| last_irs_check_date | String | Last IRS check datetime for a cached result, or empty while pending |
| created_date | String | Request created datetime (YYYY-MM-DDTHH:MM:SSZ) |
| updated_date | String | Request updated datetime (YYYY-MM-DDTHH:MM:SSZ) |
When provisional matching is enabled for the account, the response may also include provisional fields such as provisional_service_status, provisional_code, and provisional_status.
What is the IRS code in TIN Match?
| irs_code | irs_reason |
|---|---|
| 0 | TIN and Name combination matches IRS records. |
| 1 | TIN was missing or TIN not 9-digit numeric. |
| 2 | TIN entered is not currently issued. |
| 3 | TIN and Name combination does not match IRS records. |
| 4 | Invalid TIN Matching request. |
| 5 | Duplicate TIN Matching request. Note: IRS doesn't allow more than 3 duplicates (Either TIN or Name) repeating within 24 Hrs |
| 6 | TIN and Name combination matches IRS SSN records. (or) TIN and Name combination matches IRS ITIN records. |
| 7 | TIN and Name combination matches IRS EIN records. (or) TIN and Name combination matches IRS ITIN records. |
| 8 | TIN and Name combination matches IRS SSN and EIN records. (or) TIN and Name combination matches IRS ITIN records. |
| -1 | The request is Pending (Compliancely Code) |
| 10 | Duplicate record - We're reviewing the information. (Compliancely Code) |
Duplicate Requests - In Review (Code 10)
If multiple requests are submitted within a 30-hour period using either the same Name with different TINs or the same TIN with different Names, the third request will be flagged as "In Review" (Code 10). These requests will be quarantined and processed manually, which may take a minimum of 30 minutes or longer, depending on the number of duplicate requests submitted. We recommend waiting for the specified period before submitting any further duplicate requests.
Possible Error Responses
| Response Code | Response |
|---|---|
| 400 | {"name":["This field is required."]} |
| 400 | {"tin":["This field is required."]} |
| 400 | {"name":["Name contains invalid characters (a-z, A-Z, 0-9, &, - are only allowed) and minimum length is 1"]} |
| 400 | {"tin":["TIN format is invalid/ TIN must be 9 digits"]} |
| 400 | {"tin":["Invalid TIN / TIN format is invalid / TIN must be 9 digits"]} |
| 400 | {"name":["Ensure this field has no more than 40 characters."]} |
| 400 | {"webhook_urls":["Maximum 3 URLs are allowed"]} |
| 403 | {"detail":"Authentication credentials were not provided."} |
| 403 | {"detail":"Invalid token."} |
| 403 | {"detail":"Invalid token header. No credentials provided."} |
| 403 | {"detail":"Credit limit reached! For assistance, please contact the support"} |
| 500 | Server Error |
Note: '999999999', '078051120', '111111111', '123456789', '219099999', '000000000', and 987654320-987654329 are treated as invalid TINs.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||