The API POST request format requires the content type to be multipart/form-data with a form-data key "file" containing the input file in either .csv, .xlsx, or .xls format. CSV is recommended. Upon successful submission, the response includes a success message confirming the record submission, along with details such as the ID, input file URL, status, creation information, and timestamps. Additionally, the API supports retrieving data by ID, returning information like the input file URL, result file URL, error file URL, duplicate record file results, status, and timestamps for processing and updates.

Max file size allowed is 6MB. Max number of records allowed in a single file upto 10K depending the plan.

We can prioritise the files if the file name has a suffix with Priority and a number as shown in the below example. Here, the lower number mean the higher priority (1 is highest priority, 10 is lowest). We can also allow the priority numbers in the payload. Priority in the filename has highest precedence. If multiple files have the same priority, they will be processed in the order they were received.

Ex: <file-name>-priority-<1-10>.csv

Request and Response Object Structures.

Priority in the file name will take precedence.

'file': file,
'priority': integer /*optional*/ /* value between 1-10*/
'webhook_urls': string /*optional*/ /* A valid endpoint which return 2XX */

{
    "success_message": string,
    "data": {
        "id": integer,
        "input_file_url": string,
      	"regular_file_url": string/null,
        "result_file_url": string/null,
        "error_file_url": string/null,
        "duplicate_record_file_results": Array,
        "original_file_name": string,
        "status": string,
        "priority": integer,
        "result_updated_at": string,
        "created_by": string,
        "created_at": string,
        "updated_at": string
    },
    "success": boolean
}

📘
The file must contain header and data validations as specified

Key	Value
file	input file (request format required)	Mandatory. Request format required, -(hyphen), _(underscore) are allowed as filename. Max file size is 6MB Max allowed records per file is 1Lakh
priority	1-10	Optional. 1 is highest priority, 10 is lowest
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

File format in csv:
name;tax_id (or) name;tin
Download the sample format here

Note: Expected a header column in the input file as below.

Column name	Type	Validations	Comments
name (Mandatory)	String	a-z, A-Z, 0-9, &(Ampersand), -(hyphen) are only allowed in the Name. Name should not start with a number Min character length of the Name is 1 and Max is 40 characters	--
tax_id/tin (Mandatory)	String	Tax_id should be 9 digits. (Prefill with 0s if the TIN is not 9 digits.) The following Tax_id are not allowed '999999999', '078051120', '111111111', '123456789', '219099999', '123456789', '000000000' and 987654320 - 987654329	--
metadata (Optional)	String	Allowed upto 64 characters	Just an identifier which will be returned back with the result file A JSON string is also accepted.

Expected result file columns.

Column name	Type	Validations	Comments
name (Mandatory)	String	--	Name which is given in the input file.
tax_id/tin (Mandatory)	String	--	tax_id/tin which is given in the input file.
result_code	Integer	IRS result code 0-8, -1 and 10. Please check below table for more details on result code.	This column will not be returned if the file is an error file
metadata (Optional)	String	--	Identifier which is given in the input file. A JSON string is also accepted.

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)

Here are the possible statuses you may encounter during the life cycle of a Bulk TIN match.

pending: The request file has been accepted.

processing: The request is currently being processed. If any of the partial data is invalid and error file is created and returned.

completed: The request has been processed, and the final result is available including the TIN duplicate results. You can find more details about the TIN duplicate in the Guides section.

error: There are issues with the file, such as corruption, unreadable data, unspecified columns, or a format that does not match the specified file data structure or when all the data in the file is not valid.

Webhooks are triggered when status is,

"completed",
"error" (When there is an issue with the file or entire data), and
"processing" but when there is an error file (This is when partial data is invalid out of entire file)

Sample Requests and Responses.

'file': 'Bulk tin file',
'priority': 1
'webhook_urls: "<webhook endpoint>"

{
    "success_message": "Record submitted successfully",
    "data": {
        "id": 19,
        "input_file_url": "https://app1.compliancely.com/app/file/download/secure/eyJhbGciOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXxxIjoidGF4X3RyYW5zY3JpcHRfcmVwb3J0IiwiZmlsZV9tb2RlIjoiczMifQ.LRQJIynM9mgQnW99UIzgHvceKlVYX-3LOKSaqw_ruXo",
      	"regular_file_url": "",
        "result_file_url": "",
        "error_file_url": "",
        "duplicate_record_file_results": [],
        "original_file_name": "1MTINMATCH_priority-1.csv",
        "status": "pending",
        "priority": 1,
        "result_updated_at": "",
        "created_by": "compliancely",
        "created_at": "2024-07-09T08:38:52.730411Z",
        "updated_at": "2024-07-09T08:38:52.730427Z"
    },
    "success": true
}

{
    "detail": "Authentication credentials were not provided."
}

{
    "errors": [
        {
            "detail": "Credit limit reached! For assistance, please contact the support"
        }
    ],
    "data": null,
    "success": false
}

{
    "detail": "Invalid token."
}

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

200

400Invalid file provided.

401Authentication credentials were not provided.

403No active credits.