Vehicle Intelligence - Batch Status

Introduction

The Batch Status API returns the live progress of a batch you submitted through the Batch Upload API, along with download links for its output files once they exist. It is a read-only polling endpoint — calling it never changes the batch. A batch moves through four statuses. `PROCESSING` means the main pass is still running. `RETRIAL_IN_PROGRESS` means the main pass finished and vehicles that could not be found are being re-attempted over a configured window; this only occurs if automated retrial is enabled for your organisation. `COMPLETED` is terminal. `STOPPED` means the batch was halted before finishing, and any output reflects only what had been processed at that point. Counts are derived from per-status tallies rather than a single processed counter, so they always reconcile: `successCases` counts vehicles resolved successfully, `failedCases` is every other processed outcome, and `processedCases` is the sum. A vehicle that was rejected because its registration number was malformed is counted under status code `400`, so it appears in `failedCases` and in `processedCases`, never in `successCases`. Output files appear as arrays because a batch that goes through automated retrial produces a second pair — the first covering vehicles resolved in the main pass, the second covering the retrial outcomes. Until output exists, both arrays are empty. Download URLs are time-limited and re-issued on each call, so request a fresh one rather than storing them.

How to call the API

Pass your API token in the `Authorization` header. The `batchId` is supplied as a query parameter.

Successful responses are wrapped in a result object, errors are wrapped in an error object carrying a machine-readable reason and a human-readable message. Branch on reason, not on message.

API Input Guidelines

batchId is required and must be the exact 24-character hex value returned by the Batch Upload API. Any other format returns a 400 without a lookup.

The batch must belong to your organisation. Requesting a batch belonging to another organisation returns BATCH_NOT_FOUND, identical to a batch that does not exist.

Poll at a sensible interval. Status changes are driven by batch size, so for large batches poll every few minutes rather than continuously.

Output URLs are time-limited. Download files promptly and do not cache or share the URLs; call the endpoint again to obtain fresh ones.

hypothecationPercentage is only present when hypothecation checking is enabled for the batch. Treat its absence as "not applicable", not as zero.

Output URL retrieval is best-effort. If output links cannot be produced at that moment, the call still succeeds and returns the status payload with empty outputCsv and outputZip arrays — retry rather than treating it as a failure.

Sample Curl

Preproduction

Production

curl --location 'https://api-preproduction.signzy.app/api/v3/vi-dashboard/batch/status?batchId=68a1f4c2d9e3b7a1c4f20b19' \
--header 'Authorization: <Auth Token>'

curl --location 'https://api.signzy.app/api/v3/vi-dashboard/batch/status?batchId=68a1f4c2d9e3b7a1c4f20b19' \
--header 'Authorization: <Auth Token>'

Input Parameters

Parameter	Description	Required
Authorization	Your API token, passed as a request header.	Yes
Content-Type	Not required for this request; no request body is sent.	No
batchId	Query parameter. The 24-character hex batch identifier returned by the Batch Upload API.	Yes

Sample Response

{
  "result": {
    "batchId": "68a1f4c2d9e3b7a1c4f20b19",
    "batchName": "AUGUST_FLEET_03",
    "status": "STOPPED",
    "inputType": "REVERSE_RC",
    "totalCases": 1250,
    "processedCases": 612,
    "failedCases": 41,
    "successCases": 571,
    "registrationPercentage": 46,
    "duplicateVehiclesCount": 4,
    "makerCount": 11,
    "pdfNamingTemplate": null,
    "pdfFormat": null,
    "createdAt": "2026-08-19T09:14:22.418Z",
    "statusCounts": {
      "200": 571,
      "404": 41
    },
    "outputCsv": [
      {
        "name": "AUGUST_FLEET_03_output.csv",
        "url": "https://storage.example.com/AUGUST_FLEET_03_output.csv?signature=..."
      }
    ],
    "outputZip": []
  }
}

Response Parameters

PARAMETER NAME	REQUIRED/OPTIONAL	DATA TYPE	DESCRIPTION
batchId	Required	String	The 24-character hex batch identifier.
batchName	Required	String	The batch name, as stored (uppercased and trimmed).
status	Required	String	One of PROCESSING, RETRIAL_IN_PROGRESS, COMPLETED, STOPPED.
inputType	Required	String	One of DETAIL_RC, REVERSE_RC.
totalCases	Required	Number	Total vehicles in the batch.
processedCases	Required	Number	Vehicles that have reached a final outcome, successful or not.
failedCases	Required	Number	Processed vehicles that did not resolve successfully. Equals processedCases minus successCases.
successCases	Required	Number	Vehicles resolved successfully.
hypothecationPercentage	Optional	Number	Percentage of the batch whose financier matched your configured bank. Present only when hypothecation checking is enabled for the batch.
registrationPercentage	Required	Number	successCases as a whole-number percentage of totalCases. Returns 0 when totalCases is 0.
duplicateVehiclesCount	Required	Number	Vehicles in this batch identified as duplicates.
makerCount	Required	Number	Count of distinct manufacturers found across the batch. Populated once output is generated.
pdfNamingTemplate	Required	String or null	The PDF filename template used for this batch. null when PDF generation is not in use.
pdfFormat	Required	String or null	Name of the PDF template applied. null when PDF generation is not in use.
createdAt	Required	String	ISO 8601 timestamp of when the batch was created.
statusCounts	Required	Object	Map of outcome code to count, for example {"200": 1163, "404": 82}. 200 is a successful lookup; 400 is a vehicle rejected as malformed before lookup; 404 is a vehicle not found at source. Keys present depend on outcomes actually seen.
outputCsv	Required	Array of objects	Output CSV files. Empty until output exists.
outputCsv[].name	Required	String	Suggested filename.
outputCsv[].url	Required	String	Time-limited download URL, re-issued on each call.
outputZip	Required	Array of objects	Output ZIP archives of generated PDFs. Empty until output exists, and always empty when PDF generation is not in use.
outputZip[].name	Required	String	Suggested filename.
outputZip[].url	Required	String	Time-limited download URL, re-issued on each call.

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