> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.dyspach.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Import shipments (file)

> Push shipments as a CSV or Excel file in the published structure.

<Note>
  **`POST`** `/v1/org/shipments/imports/file`
</Note>

The same [published structure](/guides/shipment-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.

<Info>
  Start from [shipments-template.csv](/templates/shipments-template.csv) — the header
  row with a worked example, including a two-line shipment.
</Info>

## Authorization

<ParamField header="x-api-key" type="string" required>
  Your organisation API key (`dzk_live_…`).
</ParamField>

## Form fields

<ParamField body="file" type="file" required>
  `.csv` or `.xlsx`, up to **50 MB**. The first row must be the header row.
</ParamField>

<ParamField body="sourceDetails" type="string">
  Your own reference for this push. Defaults to the filename.
</ParamField>

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

```json theme={null}
{
  "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](/api-reference/get-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                                                                                     |

<RequestExample>
  ```bash cURL theme={null}
  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"
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "importId": "9f2b1c44-0d3e-4a71-9b52-0f4c1e77a8d1",
    "status": "queued",
    "source": "file",
    "statusUrl": "/v1/org/shipments/imports/9f2b1c44-0d3e-4a71-9b52-0f4c1e77a8d1"
  }
  ```

  ```json 400 theme={null}
  {
    "statusCode": 400,
    "message": "Invalid file structure — missing required column(s): originSuburb",
    "error": "Bad Request"
  }
  ```
</ResponseExample>