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": {
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "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": {
    "location_id": null,
    "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-15T09:00:00+02:00",
    "till": "2026-04-15T12:00:00+02:00",
    "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
}

Create a shipment order from the specified origin location. The destination is automatically determined based on the location’s configuration.

Request

Body parameters

location_id

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.

appointment_id

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.

pickup_date

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.

pickup_time_from

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.

pickup_time_till

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.

package_count

integer

default:"1"

Number of packages. Defaults to 1.

weight

number

default:"1"

Weight in kg. Defaults to 1.

pickup_remarks

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.

notes

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).

status

string

required

Shipment lifecycle status. One of pending, in_transit, delivered, fault, or cancelled.

logistics_provider

string

required

Logistics provider. One of go, dhl, or tof.

tracking_number

string

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

origin

object

Pickup address. May be null.

Show address object

location_id

string

Test location UUID this address resolves to. null for preset/inline addresses. Use to correlate with List Locations.

name

string

required

Company or location name.

street

string

required

Street name.

house_number

string

required

House number.

postal_code

string

required

Postal/ZIP code.

city

string

required

City.

country

string

required

ISO 3166-1 alpha-2 country code.

phone

string

Contact phone number. May be null.

string

Contact email. May be null.

destination

object

Delivery address. Same structure as origin. May be null.

pickup

object

Scheduled pickup window. May be null.

Show pickup object

from

string

required

Start of pickup window (ISO 8601 with timezone offset).

till

string

required

End of pickup window (ISO 8601 with timezone offset).

timezone

string

required

IANA timezone of the pickup location (e.g., Europe/Berlin).

notes

string

Optional notes. May be null.

status_updates

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.

appointments

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.

created_at

string

required

Creation timestamp (ISO 8601).

updated_at

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": {
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "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": {
    "location_id": null,
    "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-15T09:00:00+02:00",
    "till": "2026-04-15T12:00:00+02:00",
    "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
}

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": {
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "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": {
    "location_id": null,
    "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-15T09:00:00+02:00",
    "till": "2026-04-15T12:00:00+02:00",
    "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
}

​Request

​Body parameters

​Response

​Error responses

Request

Body parameters

Response

Error responses