TIN Match (Hybrid)

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 Name	Field Type	Mandatory/Optional	Description
tin	String	Mandatory	9 digits without any special characters
name	String	Mandatory	Not more than 40 characters. No special characters allowed except ampersand (&), hyphen(-)
webhook_urls	List of String	Optional	A 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": [ "This field may not be blank." ] }
	{ "tin": [ "This field may not be blank." ] }
	{ "name": [ "Ensure this field has no more than 40 characters." ] }
	{ "tin": [ "TIN format is invalid/ TIN must be 9 digits" ] }
	{ "name": [ "Business name should contain at least one alphabet" ] }
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