TIN Match Request (Asynchronous)

This endpoint will be used to submit tin and name match asynchronous requests.

Credit Message Error - {"code": "credit_message", "message": "Credit limit reached! For assistance, please contact the support"}

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

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 passing a Business Name or an Ind
}

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

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

{
   "tin": a TIN check by passing a Business Name or an Individual name a
}

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

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!