TIN Match (Hybrid)

TIN Sync search by ID

You can perform a TIN check by providing a Business Name or an Individual Name along with their corresponding EIN or SSN. This API call can work both synchronously and asynchronously. The response will include a request ID. The API first attempts to give you the result within the same call, typically within 30 seconds.

If processing a record takes more than 30 seconds due to IRS issues, timeouts, or outages, the record will be queued and processed when the IRS is stable. To check the result, you can either use the GET API call with the request ID or receive a notification at the webhook URL you provided. A message key is returned in the response after a 30-second timeout.

Note: Webhook URLs are stored and activated solely if the endpoint (api/v1/tin/match/tin/match/) encounters a timeout.

{
    "tin": string,
    "name": string,
    “webhook_urls”: [string]
}
{
  "id": interger,
  "name": string,
  "tin": string,
  "status": string,
  "created_by": string,
  "irs_code": integer,
  "irs_reason": string,
  "irs_service_status": string,
  "last_irs_check_date": string,
  "created_date": string,
  "updated_date": string,
  "message": string
   
  }

Request Parameters:

Field NameField TypeMandatory/OptionalDescription
tinStringMandatory9 digits without any special characters
nameStringMandatoryNot more than 40 characters. No special characters allowed except ampersand (&), hyphen(-)
webhook_urlsList of StringOptionalA Valid endpoint should return a success status 2xx. Once the result is available we will post it to the endpoint. Read more on Webhooks

Response Parameters:

Field Name

Field Type

Description

id

Integer

ID is given by the application for future reference

name

String

Submitted Name while POST request

tin

String

Submitted TIN while POST request

status

String

Represents what state the request is in. Possible statuses are Pending / TIN Matched / Did Not Match / In Review

irs_code

Integer

Code given by IRS 0-8, Additional codes by Compliancely are -1 & 10

irs_reason

String

IRS Reason for mentioned IRS Code

irs_service_status

String

Represents if the IRS is running at the time of request. Possible values are
RUNNING (or) THE IRS TIN MATCHING SERVICE IS SLOW OR CURRENTLY EXPERIENCING AN OUTAGE

last_irs_check_date

Date String

Last IRS check date of the cached result.

message

String (optional). Returns if the result_code is -1

The request is taking longer than usual. You can use the GET API with the request ID [<req_id>] for the result. Alternatively, if you've given a webhook URL, we'll notify you of the results.

created_by

String

Username who submits the POST request

created_date

Date String

Request created date

updated_date

Date String

Request updated date

What is the IRS code in TIN Match?

IRS provides the results represented as code for each request. Please check the below table to see what each code represents

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 the more than 3 duplicates (Either TIN or Name) repeating with in 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": a TIN check by providing a Business Name or an
}

{
"tin": a TIN check by providing a Business Name or an
}

{
"name": a TIN check by providing a Business Name or an Individual Name along
}

{
"tin": m a TIN check by providing a Business Name or an Individual Nam
}

{
"name": a TIN check by providing a Business Name or an Individual Name along
}

403

{"detail": "Invalid token header. No credentials provided."}

{"detail": "Invalid token."}

{"detail": "Credit limit reached! For assistance, please contact the support"}

500

Server Error

Note: '999999999', '078051120', '111111111', '123456789', '219099999', '123456789', '000000000', and 987654320 - 987654329 are treated as invalid TINs

Language
Credentials
Basic
base64
:
Click Try It! to start a request and see the response here!