Create Shipment

POST

api

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",
    "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,
  "origin": {
    "name": "Aniva Berlin Mitte",
    "street": "Unter den Linden",
    "house_number": "42",
    "postal_code": "10117",
    "city": "Berlin",
    "country": "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": "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"
    }
  ],
  "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. The destination is automatically determined based on the location’s configuration.

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

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

Optional internal notes. Maximum 128 characters.

Response

On success, the API returns 201 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, or tof.

string

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

object

Pickup address. May be null.

Show address object

string

required

Company or location name.

string

required

Street name.

string

required

House number.

string

required

Postal/ZIP code.

string

required

City.

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). Each entry has a status (free-form provider-sourced label) and time (ISO 8601). Empty array immediately after creation; populated by the hourly sync as the provider reports events.

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.

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.
`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.
`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",
    "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,
  "origin": {
    "name": "Aniva Berlin Mitte",
    "street": "Unter den Linden",
    "house_number": "42",
    "postal_code": "10117",
    "city": "Berlin",
    "country": "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": "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"
    }
  ],
  "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
}

Download Document

List 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",
    "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,
  "origin": {
    "name": "Aniva Berlin Mitte",
    "street": "Unter den Linden",
    "house_number": "42",
    "postal_code": "10117",
    "city": "Berlin",
    "country": "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": "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"
    }
  ],
  "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
}

Health

Profiles

Appointments

Home Kit Orders

Biomarkers

Panels

Units

Locations

Documents

Shipments

Create Shipment

Request

Body parameters

Response

Error responses

​Request

​Body parameters

​Response

​Error responses

Request

Body parameters

Response

Error responses