Shipments
Get Shipment
Retrieve a shipment by its reference ID
GET
/
api
/
v1
/
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",
"company_name": null,
"street": "Unter den Linden",
"house_number": "42",
"address_line_2": null,
"postal_code": "10117",
"city": "Berlin",
"state": null,
"country_code": "DE",
"phone": "+4930987654321",
"email": "berlin-mitte@anivahealth.com"
},
"destination": {
"name": "LabClinic GmbH",
"company_name": null,
"street": "Laborstraße",
"house_number": "10",
"address_line_2": null,
"postal_code": "80331",
"city": "München",
"state": null,
"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 returns200 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, dhl_warenpost, tof, rotrunner, rapido or
ups. A home-kit parcel is dhl_parcel, or dhl_warenpost when it goes abroad as Warenpost
International.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
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
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
Show pickup object
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
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.
Only the appointments in your access context are listed.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. Only the orders in your access context are listed. See
Access.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. A parcel is in your access context when at least one linked appointment or home-kit order is. |
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",
"company_name": null,
"street": "Unter den Linden",
"house_number": "42",
"address_line_2": null,
"postal_code": "10117",
"city": "Berlin",
"state": null,
"country_code": "DE",
"phone": "+4930987654321",
"email": "berlin-mitte@anivahealth.com"
},
"destination": {
"name": "LabClinic GmbH",
"company_name": null,
"street": "Laborstraße",
"house_number": "10",
"address_line_2": null,
"postal_code": "80331",
"city": "München",
"state": null,
"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"
}
⌘I
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",
"company_name": null,
"street": "Unter den Linden",
"house_number": "42",
"address_line_2": null,
"postal_code": "10117",
"city": "Berlin",
"state": null,
"country_code": "DE",
"phone": "+4930987654321",
"email": "berlin-mitte@anivahealth.com"
},
"destination": {
"name": "LabClinic GmbH",
"company_name": null,
"street": "Laborstraße",
"house_number": "10",
"address_line_2": null,
"postal_code": "80331",
"city": "München",
"state": null,
"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"
}