Bulk File Matching

Bulk File Matching

The Bulk File Matching endpoint allows you to submit a file for verification and enable one or more verification services, including TIN Matching, OFAC Verification, Non-Profit Verification, and DMF Verification.

POSTVerification/BulkFileRequest

TaxBandits supports submitting a file either by providing an existing FileId or by providing the file as a byte array in the request body.

You can also configure service-specific settings, such as the minimum matching score for OFAC verification and whether TIN details should be masked in the response file delivered through the webhook. Upon successful submission, the endpoint returns a unique SubmissionId along with the submitted file details, total record count, Submission status, submission timestamp, and any validation errors associated with the submission.

The submission can be tracked using the SubmissionId returned in the response. The verification results and response file can be retrieved through the configured webhook settings.

Note:
Before submitting the file, ensure that the following requirements are met:

• Provide a valid file name for the submitted file.
• Ensure that all records contain a valid TIN Type code (1 for Employer Identification Number (EIN), 2 for Social Security Number (SSN), and 3 for unknown TIN type) and a valid TIN value, which must be a 9-digit numeric value without hyphens.
• The file must contain no more than 100,000 records.
• The file size must be less than 10 MB.
• Ensure that the actual number of records in the file matches the TotalRecords value provided in the request payload for accurate tracking and traceability.
• The file submission will not be processed if duplicate records are identified under any of the following conditions:
  • The same Name and TIN are provided more than once in the file.
  • The same Name with a different TIN is provided in the file.
  • The same TIN with a different Name is provided in the file.

Sample File Format

TINType;TIN;Name;ReferenceNumber
1;456789123;John Earth Movers;Vendor_001

Status Retrieval

You can retrieve the status of the submitted file by configuring a webhook for the Bulk Verification event. This event is triggered once the processing of all records in the submitted file is completed, rejected, partially completed, or reaches any other applicable status.

The webhook response includes the verification status for each record, along with the response file containing the results for the verification services enabled for the submission.

To know more about configuring Bulk Verification, click here.

The following are the possible status codes and statuses returned for the submitted file:

Status Codes and Statuses

Status Code	Status	Status Message
BULK_FILE_001	ORDER_RECEIVED	Bulk File Request order received
BULK_FILE_002	SENT_TO_IRS	Bulk File Request has been sent to the IRS for verification
BULK_FILE_003	PARTIALLY_COMPLETED	The IRS has processed part of the records provided in the Bulk File order
BULK_FILE_004	COMPLETED	Bulk File Request has been verified successfully
BULK_FILE_005	REJECTED	Bulk File Request has been rejected due to duplicate Name and TIN available in the file

Request Body

Field	Type	Description
SubmissionManifest	object	SubmissionManifest provides brief information about a particular file submission as a whole. It contains information on the services to be included, such as TIN Matching, OFAC Verification, Non-Profit Verification, and DMF Verification, along with configuration options to determine whether TIN details should be masked in the response file.
Services	object[]	Object to identify the verification services to be enabled for the submitted file. Allowed values "TINMATCH", "OFAC", "NON_PROFIT", "DMF"
OFAC	object	Object used to configure the OFAC verification service for records in the submitted file.
MinScore	string	Minimum score required to match the records provided in the submission file during the record-matching verification process for OFAC verification. Size Range: 50-100
IsMaskTINInResponse	Boolean	If true identifies that the TIN details should be masked in the response file generated through the webhook.
SubmissionData	object	SubmissionData provides brief information about a file submission and record details.
FileName	string	Name of the file to be submitted for verification services.
FileId	GUID	Unique identifier of the file to be submitted Note: If FileId is provided, FileName and BulkFile (byte array) can be set to null.
BulkFile	Byte Array	Byte array containing the file to be submitted for verification.
TotalRecords	string	Total number of records contained in the submitted file.

Response Body

Field	Type	Description
SubmissionId	GUID	A unique identifier of a submission
FileName	string	Returns the file name
TotalRecords	string	Returns the total number of records in the submitted file
Status	string	Returns the status of the file submitted
StatusCd	string	Returns the status code of the status
StatusMessage	string	Returns any additional informaiton about the file submitted
SubmittedAt	string	Retruns date when the return is submitted.
Errors	object[]	Shows the error information of state returns
Id	string	Returns the validation error ID.
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

{
    "SubmissionManifest": {
        "Services": [
            "TINMATCH",
            "OFAC",
            "NON_PROFIT",
            "DMF",
        ],
        "OFAC": {
            "MinScore": 90
        },
        "IsMaskTINInResponse": true
    },
    "SubmissionData": {
        "FileName": "TIN_CHECK.txt",
        "FileId": "",
        "BulkFile": "",
        "TotalRecords": 15000
    }
}

Response JSON

{
   "SubmissionId": "31ea464a-ff03-46db-92ce-14e355a132bb",
   "FileName": "TIN_CHECK.txt",
   "TotalRecords": 15000,
   "Status": "ORDER_RECEIVED",
   "StatusCd": "BULK_FILE_001",
   "StatusMessage": "Bulk File Request order has been received",
   "SubmittedAt": "2026-08-20T09:14:32Z",
   "Errors": null
}

Bulk File Matching Webhook Response

{
  "SubmissionId": "31ea464a-ff03-46db-92ce-14e355a132bb",
  "FileName": "TIN_CHECK.txt",
  "Status": "PARTIALLY_COMPLETED",
  "StatusCd": "BULK_FILE_003",
  "StatusMessage": "Part of the records provided in the Bulk File order has been processed by the IRS",
  "TotalRecords": 15000,
  "TotalFiles": 2,
  "IsFinal": false,
  "File": {
    "FileSequence": 1,
    "RecordsInFile": 14500,
    "ResponseFilePath": ""
  },
  "Errors": null
}