Vehicle Intelligence - Batch Upload

Introduction

The Batch Upload API lets you submit a CSV of vehicles for bulk registration-certificate (RC) processing. You upload the file, we validate it synchronously, and we return a batchId immediately. Processing then continues asynchronously — poll the Batch Status API with that batchId to track progress and collect output files.

There are two input types. DETAIL_RC looks vehicles up by registration number and expects a Vehicle Number column. REVERSE_RC looks them up by chassis and engine number and expects Chassis Number and Engine Number columns. The input type you pass determines which columns are mandatory and in which position they must appear.

Validation happens at two levels, and the distinction matters. File-level problems reject the whole upload with a 400 — a missing required column, a column in the wrong position, an empty value in a required column, an oversized file, or a value exceeding a per-column length cap. Row-level problems do not. If a registration number is present but not a well-formed Indian plate, that single row is recorded with status code 400 in the output file and the rest of the batch proceeds normally. A single malformed row will never force you to re-edit and re-upload a large file.

batchName is uppercased and trimmed before it is stored, and must be unique within your organisation. Re-using a name returns a 409 rather than overwriting or appending, so treat the name as an identifier you control.

How to call the API

Pass your API token in the Authorization header. The request body is multipart/form-data, not JSON, because it carries a file.

API Input Guidelines

file, batchName, inputType and userEmail are required. pdfNameTemplate is required only when PDF generation is enabled for your organisation.

The file must have a .csv extension and must be sent under the form field name file.

Maximum file size is 15 MB. Maximum 50,000 data rows and 15 columns.

inputType must be exactly DETAIL_RC or REVERSE_RC. It is case-sensitive.

Column position is enforced. For DETAIL_RC, Vehicle Number must be the first column. For REVERSE_RC, Chassis Number must be first and Engine Number second.

Required columns must be non-empty in every row. Blank rows at the end of the file are ignored; a blank row between data rows is rejected.

Per-cell length caps apply: 25 characters for Vehicle Number, Chassis Number and Engine Number; 10 for Owner Count, Cubic Capacity, Gross Vehicle Weight and Seating Capacity; 75 for every other column, including columns you add yourself.

Values are trimmed automatically. Identifier columns are also uppercased, and internal spaces are stripped from chassis and engine numbers, so mh12ab1234 and MH12AB1234 are equivalent.

If a matching feature is enabled for your organisation, its input column must be present as a header, though individual cells may be blank. Owner Name for owner-name match, Insurer Name for insurer match, Owner Count for owner-count match, Financer Name for financier match, and all six of Make, Model Variant, Fuel Type, Cubic Capacity, Gross Vehicle Weight, Seating Capacity for MMV match.

When PDF generation is enabled, every column referenced in pdfNameTemplate must exist, must be non-empty in every row, and the combination of those columns must be unique per row — otherwise two vehicles would produce the same PDF filename.

batchName must be unique within your organisation. Comparison is on the uppercased, trimmed value.

userEmail must belong to an active user in your organisation who holds the batch-initiate permission.

You may include additional columns beyond the required ones. They are carried through to the output file unchanged.

Sample Curl

Preproduction

Production

curl --location 'https://api-preproduction.signzy.app/api/v3/vi-dashboard/batch/upload' \
--header 'Authorization: <Auth Token>' \
--form 'file=@"/path/to/vehicles.csv"' \
--form 'batchName="AUGUST_FLEET_01"' \
--form 'inputType="DETAIL_RC"' \
--form 'pdfNameTemplate="<Vehicle Number>_report"' \
--form 'userEmail="[email protected]"'

curl --location 'https://api.signzy.app/api/v3/vi-dashboard/batch/upload' \
--header 'Authorization: <Auth Token>' \
--form 'file=@"/path/to/vehicles.csv"' \
--form 'batchName="AUGUST_FLEET_01"' \
--form 'inputType="DETAIL_RC"' \
--form 'pdfNameTemplate="<Vehicle Number>_report"' \
--form 'userEmail="[email protected]"'

Input Parameters

Parameter	Description	Required
Authorization	Your API token, passed as a request header.	Yes
Content-Type	Must be multipart/form-data.	Yes
file	The CSV file of vehicles. Must have a .csv extension and be at most 15 MB.	Yes
batchName	Your name for this batch. Uppercased and trimmed on save; must be unique within your organisation.	Yes
inputType	DETAIL_RC or REVERSE_RC. Determines which columns are mandatory.	Yes
userEmail	Email of the user initiating the batch. Must be an active user in your organisation with batch-initiate permission.	Yes
pdfNameTemplate	Template for generated PDF filenames, referencing CSV columns in angle brackets, e.g. <Vehicle Number>_report.	Conditional — required only when PDF generation is enabled for your organisation

Sample Response

{
  "result": {
    "batchId": "68a1f4c2d9e3b7a1c4f20b19",
    "batchName": "AUGUST_FLEET_01",
    "totalCases": 1250,
    "status": "PROCESSING"
  }
}

Response Parameters

PARAMETER NAME	REQUIRED/OPTIONAL	DATA TYPE	DESCRIPTION
batchId	Required	String	24-character hex identifier for the batch. Pass this to the Batch Status API.
batchName	Required	String	The stored batch name, uppercased and trimmed.
totalCases	Required	Number	Number of data rows accepted from the CSV. Blank rows are excluded.
status	Required	String	Always PROCESSING on a successful upload. Subsequent values are returned by the Batch Status API: PROCESSING, RETRIAL_IN_PROGRESS, COMPLETED, STOPPED.

Status Codes

CODE	REASON	MESSAGE
200	—	Success. The batch was accepted and is now processing.
400	BAD_REQUEST	Request validation failed. The message field describes the specific problem, such as a missing or malformed field, an unsupported file type, an exceeded size or row limit, or a CSV column that is missing, misordered, empty, too long, or duplicated.
401	UNAUTHORIZED	Unauthorized
403	ORG_NOT_ACTIVE	Organization is not active
403	FORBIDDEN	Forbidden: user lacks permission to initiate batches
404	USER_NOT_FOUND	User not found
409	DUPLICATE_BATCH_NAME	A batch with this name already exists for this organization
500	INTERNAL_ERROR	Internal Server Error

Getting help

Please feel free to contact us if you have any questions, require clarification, or have ideas for how to make the documents or any of our services better.

You can reach out to us at [email protected].