TIN Match Request (Asynchronous)

You can submit a TIN check by passing a Business Name or an Individual name along with their EIN or SSN accordingly. It is an asynchronous API call in which a request-id is provided in the response. Need to use the GET API call by ID (request id) to see the result. Please check the How API Works section on how the asynchronous API life cycle works.

{
    "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,
   
  }

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.
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.