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

# Check an import

> Poll an import for its status and counts.

<Note>
  **`GET`** `/v1/org/shipments/imports/{importId}`
</Note>

Reports where the import is and what it did.

<Info>
  Imports run on a queue, one at a time per organisation, so a push typically finishes in
  **one to three minutes**. Poll every 30 seconds or so — a tight loop will just spend
  your rate limit.
</Info>

## Authorization

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

## Path parameters

<ParamField path="importId" type="string" required>
  The `importId` returned when the import was accepted.
</ParamField>

## Status values

| Status       | Meaning                                                                       |
| ------------ | ----------------------------------------------------------------------------- |
| `queued`     | Accepted, waiting to start                                                    |
| `processing` | Running                                                                       |
| `completed`  | Finished — **check the counts**, some rows may still have been rejected       |
| `failed`     | The import itself could not run; nothing was written. `errorMessage` says why |
| `cancelled`  | Stopped from the Dyspach portal                                               |

## Counts

| Field              | Meaning                                                                                                                                                         |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `counts.received`  | **Rows** read from your submission — a shipment with three goods lines is three rows, so this is not the shipment count echoed back when the batch was accepted |
| `counts.processed` | Shipments written to the ledger                                                                                                                                 |
| `counts.failed`    | Rows rejected — list them with [the errors endpoint](/api-reference/get-import-errors)                                                                          |

`completed` with failures is the normal case, not an exception: valid shipments are never
held back because other rows were wrong.

`errorReportUrl` is a **short-lived signed link** to a spreadsheet of the rejected rows
with their reasons, available once the import finishes. It expires after an hour — read
the import again for a fresh one.

## Recovering from `failed`

A `failed` import wrote nothing. Re-send the same batch — shipments are matched on
`shipmentId`, so replaying a push is always safe, even if an earlier attempt got part way.

## Errors

| Status | When                                        |
| ------ | ------------------------------------------- |
| `401`  | Missing or invalid API key                  |
| `404`  | No import with that id in your organisation |

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.dyspach.com/v1/org/shipments/imports/9f2b1c44-0d3e-4a71-9b52-0f4c1e77a8d1 \
    -H "x-api-key: $DYSPACH_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "importId": "9f2b1c44-0d3e-4a71-9b52-0f4c1e77a8d1",
    "source": "data",
    "status": "completed",
    "progress": 100,
    "counts": { "received": 1000, "processed": 900, "failed": 100 },
    "sourceDetails": "org:Acme 3PL / nightly-2026-08-14",
    "submittedAt": "2026-08-14T02:20:11.000Z",
    "startedAt": "2026-08-14T02:20:19.000Z",
    "finishedAt": "2026-08-14T02:23:02.000Z",
    "errorMessage": null,
    "errorReportUrl": "https://dyspach-media.s3.ap-southeast-2.amazonaws.com/long-processing/errors-9f2b1c44.xlsx?X-Amz-Signature=..."
  }
  ```
</ResponseExample>