Skip to main content
GET
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, 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
Who printed the label: aniva or external. Only aniva shipments accept Update and Cancel; an external parcel 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.
​
object
Delivery address. Same structure as origin. May be null.
​
object
Scheduled pickup window. May be null.
​
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.
​
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