Import shipments (file)

POST /v1/org/shipments/imports/file

The same published structure, delivered as a file — for nightly extracts and larger volumes, or simply because a file is what your system already produces. One row per goods line. Repeat the shipment columns on each line of a multi-line shipment and keep those lines together. Column order does not matter and optional columns may be omitted.

Start from shipments-template.csv — the header row with a worked example, including a two-line shipment.

Authorization

string

required

Your organisation API key (dzk_live_…).

Form fields

file

required

.csv or .xlsx, up to 50 MB. The first row must be the header row.

string

Your own reference for this push. Defaults to the filename.

The header row is checked before anything is queued

A structure mistake is yours to fix, so you hear about it on the request rather than minutes later. The response names exactly what is wrong:

{
  "statusCode": 400,
  "message": "Invalid file structure — missing required column(s): itemType; unrecognised column(s): weight_kg",
  "error": "Bad Request"
}

Once the header passes, the file is queued and every row is validated individually during the import — see Check an import.

Response

202 Accepted, the same shape as the JSON lane, except received is absent — the row count is not known until the file is parsed.

Errors

Status	When
`400`	File missing, empty, unreadable, an unsupported type, or a header row that does not match the structure
`400`	`.xls` is not accepted — re-save as `.csv` or `.xlsx`
`400`	Too many imports already queued
`401`	Missing or invalid API key
`413`	File larger than 50 MB — split it
`429`	Rate limit exceeded

curl -X POST https://api.dyspach.com/v1/org/shipments/imports/file \
  -H "x-api-key: $DYSPACH_API_KEY" \
  -F "file=@shipments-2026-08-14.csv" \
  -F "sourceDetails=nightly-2026-08-14"

{
  "importId": "9f2b1c44-0d3e-4a71-9b52-0f4c1e77a8d1",
  "status": "queued",
  "source": "file",
  "statusUrl": "/v1/org/shipments/imports/9f2b1c44-0d3e-4a71-9b52-0f4c1e77a8d1"
}

{
  "statusCode": 400,
  "message": "Invalid file structure — missing required column(s): originSuburb",
  "error": "Bad Request"
}

Getting Started

Guides

Quotes

Shipments

Import shipments (file)

Authorization

Form fields

The header row is checked before anything is queued

Response

Errors

​Authorization

​Form fields

​The header row is checked before anything is queued

​Response

​Errors

Authorization

Form fields

The header row is checked before anything is queued

Response

Errors