List Shipments

GET

api

shipments

curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?limit=100&offset=0' \
  --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?home_kit_order_id=d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a' \
  --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?appointment_id=c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a&status=in_transit' \
  --header 'x-api-key: YOUR_API_KEY'

[
  {
    "id": "P2604154821",
    "status": "in_transit",
    "logistics_provider": "go",
    "tracking_number": "GO1234567890",
    "contents": "Medizinisch freigestellte Probe",
    "booked_by": "aniva",
    "paired_with": null,
    "origin": {
      "name": "Aniva Berlin Mitte",
      "street": "Unter den Linden",
      "house_number": "42",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "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_code": "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": [
      {
        "state": "in_transit",
        "code": "GO10",
        "detail_code": null,
        "status": "Shipment picked up",
        "description": "Picked up at the consignor",
        "location": "Berlin",
        "time": "2026-04-15T09:22:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "GO50",
        "detail_code": null,
        "status": "Receiving station",
        "description": null,
        "location": "HUB Niederaula",
        "time": "2026-04-15T11:18:00+02:00"
      }
    ],
    "appointments": [
      {
        "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
        "added_at": "2026-04-15T08:30:00Z"
      }
    ],
    "home_kit_orders": [],
    "synced_at": "2026-04-15T11:20:00Z",
    "created_at": "2026-04-14T16:00:00Z",
    "updated_at": "2026-04-15T11:20:00Z"
  }
]

Retrieve the shipments accessible to your API key, newest first. Every parcel is in this one list: a courier collection from a practice, the kit on its way to a home-kit patient, and the sample on its way back. Filter to one parent with appointment_id or home_kit_order_id. Requires the shipments_view or shipments_manage scope. The response comes from our database and never calls the carrier. A background sync refreshes every shipment (every 10 minutes for GO!, hourly for DHL) and synced_at on each row tells you when the carrier was last asked.

Request

Query parameters

string

Only shipments linked to this appointment (UUID). 404 when the appointment does not exist, 403 when it is outside your access context.

string

Only shipments linked to this home-kit order (UUID). Normally two rows come back — the kit on its way to the patient and the sample back to the laboratory (its destination is the lab). Same 404 / 403 rules as appointment_id.

string

Only shipments in this status. One of pending, in_transit, delivered, fault, cancelled.

integer

Maximum number of shipments to return. Defaults to 100, max 500.

integer

Number of shipments to skip. Defaults to 0. The sort is stable (created_at descending, then reference), so pages do not overlap.

Response

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

string

required

Shipment reference identifier.

string

required

Shipment lifecycle status. One of pending, in_transit, delivered, fault, or cancelled.

string

required

Logistics provider. One of go, dhl_parcel, tof, rotrunner or rapido. Every home-kit parcel is dhl_parcel.

string

External tracking number from the logistics provider. May be null.

string

Free-text description of what is in the parcel, as given at creation (e.g. "Medizinisch freigestellte Probe", "Home test kit"). Informational only — whether a parcel is heading to a laboratory is read off destination, and its counterpart off paired_with. May be null.

string

required

Who printed the label: aniva, probatix or biomes. Only aniva shipments accept Update and Cancel; a parcel booked by a fulfilment partner is tracked but returns 501 on either.

string

Reference of the other parcel of a two-parcel consignment — the parcel that carried a return label, and the parcel that label brings back. Set on both. null for a one-way parcel.

object

Pickup address. May be null.

Show address object

string

required

Recipient, company, or location name.

string

Company / c/o line. May be null.

string

required

Street name, without the house number.

string

House number. May be null.

string

Building, entrance, or floor. May be null.

string

required

City.

string

State or province. May be null.

string

required

Postal/ZIP code.

string

required

ISO 3166-1 alpha-2 country code.

string

Contact phone number. May be null.

string

Contact email. May be null.

object

Delivery address. Same structure as origin. May be null.

object

Scheduled pickup window. May be null.

Show pickup object

string

required

Start of pickup window as a UTC instant (ISO 8601 with Z suffix).

string

required

End of pickup window as a UTC instant (ISO 8601 with Z suffix).

string

required

IANA timezone of the pickup location (e.g., Europe/Berlin). Use to render from / till in pickup-location wall-clock.

string

Optional notes. May be null.

object[]

required

Chronological lifecycle events from the logistics provider (oldest first). Empty array if the provider has not reported any events yet. Use this for per-event UI, audit and the finer carrier signals; rely on status for the canonical current state.

Show status update fields

string | null

required

The event in the shipment status vocabulary — pending, in_transit, delivered or fault — so you can read a timeline without knowing the carrier’s codes. null when the event carries no state (label creation, a carrier “no information” scan, entries recorded before this field existed). Never cancelled.

string | null

required

The carrier’s own status token: GO!‘s GO10 / GO90 / GOY001, DHL’s VA / ZF / LA / ZU. null when the carrier supplied none. Stable across language translations of status.

string | null

required

The carrier’s finer token where it has one — DHL’s statusDetailed, e.g. CNRFC_NRQRD_ZF (redirected to a post office), HLDCC_SERPT_LA (ready for pickup there), DLVRD_SERPT_ZU (picked up). null for carriers without one.

string

required

Provider-sourced status label (free-form text, e.g. "Shipment picked up", "Die Sendung wurde abgeholt.").

string | null

required

An explanation of the code, or the carrier’s longer sentence. null when neither exists.

string | null

required

Where the scan happened, as the carrier names it — a GO! depot ("HUB Niederaula") or a DHL city. Free text, not a coordinate. null when the carrier reported none.

string

required

Time the event was observed (ISO 8601, with the offset the carrier reported).

ShipmentAppointmentLink[]

required

Appointments linked to this shipment, oldest-link first. Each entry is { id, added_at }; cross-reference each id against Get Appointment for the full appointment payload. Empty array when no appointments are linked.

ShipmentHomeKitOrderLink[]

required

Home-kit orders linked to this shipment, oldest-link first, in the same { id, added_at } shape. Cross-reference each id against Get Home Kit Order. Empty array for practice parcels.

string

When the shipment was last reconciled with its carrier, as a UTC instant. Reads never call the carrier — a background sync keeps shipments fresh — so this is how old the answer is. null until the first sync.

string

required

Creation timestamp (ISO 8601).

string

Last update timestamp (ISO 8601). May be null.

Error responses

Status	Description
`400`	Invalid query parameter.
`403`	Forbidden — missing scope, or the filtered appointment / home-kit order is outside your scope.
`404`	The filtered appointment or home-kit order was not found.
`500`	Internal server error.

curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?limit=100&offset=0' \
  --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?home_kit_order_id=d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a' \
  --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?appointment_id=c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a&status=in_transit' \
  --header 'x-api-key: YOUR_API_KEY'

[
  {
    "id": "P2604154821",
    "status": "in_transit",
    "logistics_provider": "go",
    "tracking_number": "GO1234567890",
    "contents": "Medizinisch freigestellte Probe",
    "booked_by": "aniva",
    "paired_with": null,
    "origin": {
      "name": "Aniva Berlin Mitte",
      "street": "Unter den Linden",
      "house_number": "42",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "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_code": "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": [
      {
        "state": "in_transit",
        "code": "GO10",
        "detail_code": null,
        "status": "Shipment picked up",
        "description": "Picked up at the consignor",
        "location": "Berlin",
        "time": "2026-04-15T09:22:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "GO50",
        "detail_code": null,
        "status": "Receiving station",
        "description": null,
        "location": "HUB Niederaula",
        "time": "2026-04-15T11:18:00+02:00"
      }
    ],
    "appointments": [
      {
        "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
        "added_at": "2026-04-15T08:30:00Z"
      }
    ],
    "home_kit_orders": [],
    "synced_at": "2026-04-15T11:20:00Z",
    "created_at": "2026-04-14T16:00:00Z",
    "updated_at": "2026-04-15T11:20:00Z"
  }
]

curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?limit=100&offset=0' \
  --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?home_kit_order_id=d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a' \
  --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?appointment_id=c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a&status=in_transit' \
  --header 'x-api-key: YOUR_API_KEY'

[
  {
    "id": "P2604154821",
    "status": "in_transit",
    "logistics_provider": "go",
    "tracking_number": "GO1234567890",
    "contents": "Medizinisch freigestellte Probe",
    "booked_by": "aniva",
    "paired_with": null,
    "origin": {
      "name": "Aniva Berlin Mitte",
      "street": "Unter den Linden",
      "house_number": "42",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "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_code": "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": [
      {
        "state": "in_transit",
        "code": "GO10",
        "detail_code": null,
        "status": "Shipment picked up",
        "description": "Picked up at the consignor",
        "location": "Berlin",
        "time": "2026-04-15T09:22:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "GO50",
        "detail_code": null,
        "status": "Receiving station",
        "description": null,
        "location": "HUB Niederaula",
        "time": "2026-04-15T11:18:00+02:00"
      }
    ],
    "appointments": [
      {
        "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
        "added_at": "2026-04-15T08:30:00Z"
      }
    ],
    "home_kit_orders": [],
    "synced_at": "2026-04-15T11:20:00Z",
    "created_at": "2026-04-14T16:00:00Z",
    "updated_at": "2026-04-15T11:20:00Z"
  }
]

Health

Profiles

Appointments

Home Kit Orders

Biomarkers

Panels

Units

Locations

Documents

Shipments

List Shipments

Request

Query parameters

Response

Error responses

​Request

​Query parameters

​Response

​Error responses

Request

Query parameters

Response

Error responses