Upload A File

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 is 1 Lakh.

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

File format in csv:
<name>;<tax_id> (or) <name>;<tin>

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

Expected result file columns.

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

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