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

# List Shipments

> Retrieve all shipments for your account

Retrieve all shipments for your API key's location groups. List reads are served from our DB
without making provider calls — an hourly background sync keeps shipments reasonably fresh
(within the last few hours). For a force-refreshed view of one shipment, use
[Get Shipment](/api/shipments/get-shipment).

## Request

This endpoint takes no request parameters.

## Response

On success, the API returns `200 OK` with an array of shipment objects.

<ResponseField name="id" type="string" required>
  Shipment reference identifier.
</ResponseField>

<ResponseField name="status" type="string" required>
  Shipment lifecycle status. One of `pending`, `in_transit`, `delivered`, `fault`, or `cancelled`.
</ResponseField>

<ResponseField name="logistics_provider" type="string" required>
  Logistics provider. One of `go`, `dhl`, or `tof`.
</ResponseField>

<ResponseField name="tracking_number" type="string">
  External tracking number from the logistics provider. May be `null`.
</ResponseField>

<ResponseField name="origin" type="object">
  Pickup address. May be `null`.

  <Expandable title="address object">
    <ResponseField name="name" type="string" required>Company or location name.</ResponseField>
    <ResponseField name="street" type="string" required>Street name.</ResponseField>
    <ResponseField name="house_number" type="string" required>House number.</ResponseField>
    <ResponseField name="postal_code" type="string" required>Postal/ZIP code.</ResponseField>
    <ResponseField name="city" type="string" required>City.</ResponseField>
    <ResponseField name="country" type="string" required>ISO 3166-1 alpha-2 country code.</ResponseField>
    <ResponseField name="phone" type="string">Contact phone number. May be `null`.</ResponseField>
    <ResponseField name="email" type="string">Contact email. May be `null`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="destination" type="object">
  Delivery address. Same structure as `origin`. May be `null`.
</ResponseField>

<ResponseField name="pickup" type="object">
  Scheduled pickup window. May be `null`.

  <Expandable title="pickup object">
    <ResponseField name="from" type="string" required>Start of pickup window as a UTC instant (ISO 8601 with `Z` suffix).</ResponseField>
    <ResponseField name="till" type="string" required>End of pickup window as a UTC instant (ISO 8601 with `Z` suffix).</ResponseField>
    <ResponseField name="timezone" type="string" required>IANA timezone of the pickup location (e.g., `Europe/Berlin`). Use to render `from` / `till` in pickup-location wall-clock.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="notes" type="string">
  Optional notes. May be `null`.
</ResponseField>

<ResponseField name="status_updates" type="object[]" required>
  Chronological lifecycle events from the logistics provider (oldest first). Each entry has a
  `status` (free-form provider-sourced label) and `time` (ISO 8601). Empty array if no events
  observed yet.
</ResponseField>

<ResponseField name="appointments" type="ShipmentAppointmentLink[]" required>
  Appointments linked to this shipment, oldest-link first. Each entry is `{ id, added_at }`;
  cross-reference each `id` against [Get Appointment](/api/appointments/get-appointment) for the
  full appointment payload. Empty array when no appointments are linked.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  Creation timestamp (ISO 8601).
</ResponseField>

<ResponseField name="updated_at" type="string">
  Last update timestamp (ISO 8601). May be `null`.
</ResponseField>

## Error responses

| Status | Description                                                      |
| ------ | ---------------------------------------------------------------- |
| `403`  | Forbidden — your API key does not have access to this operation. |
| `500`  | Internal server error.                                           |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://anivahealth.com/api/v1/shipments \
    --header 'x-api-key: YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "id": "P2604154821",
      "status": "in_transit",
      "logistics_provider": "go",
      "tracking_number": "GO1234567890",
      "origin": {
        "name": "Aniva Berlin Mitte",
        "street": "Unter den Linden",
        "house_number": "42",
        "postal_code": "10117",
        "city": "Berlin",
        "country": "DE",
        "phone": "+4930987654321",
        "email": "berlin-mitte@anivahealth.com"
      },
      "destination": {
        "name": "LabClinic GmbH",
        "street": "Laborstraße",
        "house_number": "10",
        "postal_code": "80331",
        "city": "München",
        "country": "DE",
        "phone": null,
        "email": null
      },
      "pickup": {
        "from": "2026-04-15T07:00:00Z",
        "till": "2026-04-15T10:00:00Z",
        "timezone": "Europe/Berlin"
      },
      "notes": null,
      "status_updates": [
        { "status": "Shipment picked up", "time": "2026-04-15T09:22:00Z" },
        { "status": "Receiving station", "time": "2026-04-15T11:18:00Z" }
      ],
      "appointments": [
        {
          "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
          "added_at": "2026-04-15T08:30:00Z"
        }
      ],
      "created_at": "2026-04-14T16:00:00Z",
      "updated_at": "2026-04-15T11:20:00Z"
    }
  ]
  ```
</ResponseExample>