Shipments
Create Shipment
Create a logistics shipment order with specified origin and destination
POST
/
api
/
v1
/
shipments
curl --request POST \
--url https://anivahealth.com/api/v1/shipments \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
"destination_lab": "labclinic",
"appointment_id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
"pickup_date": "2026-04-15",
"pickup_time_from": "09:00",
"pickup_time_till": "12:00",
"notes": "Handle with care — temperature-sensitive samples"
}'
{
"id": "P2604154821",
"status": "pending",
"logistics_provider": "go",
"tracking_number": null,
"contents": null,
"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": "Handle with care — temperature-sensitive samples",
"status_updates": [],
"appointments": [
{
"id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
"added_at": "2026-04-15T07:00:00Z"
}
],
"home_kit_orders": [],
"synced_at": null,
"created_at": "2026-04-15T07:00:00Z",
"updated_at": null
}
{
"error": "pickup_date must be a weekday (Monday–Friday)"
}
{
"error": "Location not found or inactive"
}
{
"error": "Logistics provider error: Pickup on weekend/holiday not possible",
"logistics_error_code": 2001
}
Create a shipment order from the specified origin location. You name the destination laboratory with
destination_lab. The shipment goes to that laboratory’s registered shipping address.
Requires the shipments_manage scope.
Send an optional Idempotency-Key header to make this create safe to retry — a repeat of the same key returns the original response instead of creating a second one. See Idempotency.
Request
Body parameters
string
required
Origin test location UUID. The location must be active and within your API key’s access context.
Use List Locations to find available location IDs.
string
required
Destination laboratory. One of
zotzklimas, labclinic, nordicgroup, biomes, imd or
quade. The shipment goes to the shipping address registered for this laboratory. A laboratory
without a registered shipping address returns 400.string
Optional appointment UUID to link this shipment to at creation time. The appointment must be
within your API key’s access context. The link surfaces inline as an entry in the shipment’s
appointments array, and conversely as an entry in the appointment’s shipments array. To link
additional appointments after creation, or remove the initial link, use Attach Appointments to
Shipment and Detach Appointments from
Shipment.string
required
Pickup date in
YYYY-MM-DD format (e.g., 2026-04-15), interpreted in the origin location’s
timezone. Must be a weekday (Monday–Friday), today or in the future. Same-day pickups are not
available after 16:00 Europe/Berlin.string
required
Earliest pickup time in
HH:MM format (e.g., 09:00), interpreted as wall-clock time in the
origin location’s timezone. Must be between 09:00 and 19:00.string
required
Latest pickup time in
HH:MM format (e.g., 12:00), interpreted as wall-clock time in the origin
location’s timezone. Must be between 09:00 and 19:00. The window (pickup_time_till - pickup_time_from) must be at least 2 hours.integer
default:"1"
Number of packages. Defaults to
1.number
default:"1"
Weight in kg. Defaults to
1.string
Instructions for the courier at pickup (consignor remarks). When omitted, the pickup address’s
stored remarks are used (or none if the address has none). Maximum 128 characters.
string
Free-text description of what is in the parcel, shown to the courier and echoed back as
contents. Maximum 40 characters (e.g. Medizinisch freigestellte Probe).string
Optional internal notes. Maximum 128 characters.
Response
On success, the API returns201 Created with the new shipment.
string
required
Shipment reference identifier (e.g.,
P2604151234).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. May be
null.string
required
Who printed the label:
aniva or external. A shipment you create is aniva.string
Reference of the other parcel of a two-parcel consignment.
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). Each entry has a
state, code, detail_code, status, description, location and time. See Get
Shipment for each field. Empty array immediately after creation.
The background sync adds events as the provider reports them.ShipmentAppointmentLink[]
required
Appointments linked to this shipment, oldest-link first. Each entry is
{ id, added_at };
cross-reference each id against Get Appointment.
Contains the appointment passed via appointment_id (if any) immediately after creation.ShipmentHomeKitOrderLink[]
required
Home-kit orders linked to this shipment, in the same
{ id, added_at } shape. Empty array for a
shipment you create.string
When the shipment was last reconciled with its carrier, as a UTC instant.
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 | Validation error — e.g., invalid date format, weekend date, pickup window too narrow, same-day cutoff exceeded. Also returned when destination_lab or the origin location has no registered address. |
403 | Forbidden — your API key does not have access to this operation or the location is outside your access context. |
404 | Location not found or inactive, or appointment_id was provided but the appointment doesn’t exist. |
409 | The Idempotency-Key was already used with a different request body, or its original request has not completed. |
500 | Internal server error. |
502 | Logistics provider rejected the request. Includes the provider’s error message. |
curl --request POST \
--url https://anivahealth.com/api/v1/shipments \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
"destination_lab": "labclinic",
"appointment_id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
"pickup_date": "2026-04-15",
"pickup_time_from": "09:00",
"pickup_time_till": "12:00",
"notes": "Handle with care — temperature-sensitive samples"
}'
{
"id": "P2604154821",
"status": "pending",
"logistics_provider": "go",
"tracking_number": null,
"contents": null,
"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": "Handle with care — temperature-sensitive samples",
"status_updates": [],
"appointments": [
{
"id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
"added_at": "2026-04-15T07:00:00Z"
}
],
"home_kit_orders": [],
"synced_at": null,
"created_at": "2026-04-15T07:00:00Z",
"updated_at": null
}
{
"error": "pickup_date must be a weekday (Monday–Friday)"
}
{
"error": "Location not found or inactive"
}
{
"error": "Logistics provider error: Pickup on weekend/holiday not possible",
"logistics_error_code": 2001
}
⌘I
curl --request POST \
--url https://anivahealth.com/api/v1/shipments \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
"destination_lab": "labclinic",
"appointment_id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
"pickup_date": "2026-04-15",
"pickup_time_from": "09:00",
"pickup_time_till": "12:00",
"notes": "Handle with care — temperature-sensitive samples"
}'
{
"id": "P2604154821",
"status": "pending",
"logistics_provider": "go",
"tracking_number": null,
"contents": null,
"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": "Handle with care — temperature-sensitive samples",
"status_updates": [],
"appointments": [
{
"id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
"added_at": "2026-04-15T07:00:00Z"
}
],
"home_kit_orders": [],
"synced_at": null,
"created_at": "2026-04-15T07:00:00Z",
"updated_at": null
}
{
"error": "pickup_date must be a weekday (Monday–Friday)"
}
{
"error": "Location not found or inactive"
}
{
"error": "Logistics provider error: Pickup on weekend/holiday not possible",
"logistics_error_code": 2001
}