Get Shipment

GET

api

shipments

{id}

curl --request GET \
  --url https://anivahealth.com/api/v1/shipments/P2604154821 \
  --header 'x-api-key: YOUR_API_KEY'

{
  "id": "P2604154821",
  "status": "in_transit",
  "logistics_provider": "go",
  "tracking_number": "GO123456789",
  "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-03T14:30:00Z",
  "updated_at": "2026-04-15T11:20:00Z"
}

{
  "error": "Shipment not found"
}

Retrieve a single shipment by its reference ID. 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 tells you when the carrier was last asked. Requires the shipments_view or shipments_manage scope.

Request

Path parameters

string

required

Shipment reference ID (e.g., P2604154821).

Response

On success, the API returns 200 OK with the shipment object.

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 ID format.
`403`	Forbidden — your API key does not have access to this operation or the shipment is outside your access context.
`404`	Shipment not found.
`500`	Internal server error.

curl --request GET \
  --url https://anivahealth.com/api/v1/shipments/P2604154821 \
  --header 'x-api-key: YOUR_API_KEY'

{
  "id": "P2604154821",
  "status": "in_transit",
  "logistics_provider": "go",
  "tracking_number": "GO123456789",
  "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-03T14:30:00Z",
  "updated_at": "2026-04-15T11:20:00Z"
}

{
  "error": "Shipment not found"
}

curl --request GET \
  --url https://anivahealth.com/api/v1/shipments/P2604154821 \
  --header 'x-api-key: YOUR_API_KEY'

{
  "id": "P2604154821",
  "status": "in_transit",
  "logistics_provider": "go",
  "tracking_number": "GO123456789",
  "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-03T14:30:00Z",
  "updated_at": "2026-04-15T11:20:00Z"
}

{
  "error": "Shipment not found"
}

Health

Profiles

Appointments

Home Kit Orders

Biomarkers

Panels

Units

Locations

Documents

Shipments

Get Shipment

Request

Path parameters

Response

Error responses

​Request

​Path parameters

​Response

​Error responses

Request

Path parameters

Response

Error responses