Attach Appointments to Shipment

POST

api

shipments

{id}

appointments

curl --request POST \
  --url https://anivahealth.com/api/v1/shipments/P2604154821/appointments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "appointment_ids": [
      "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a"
    ]
  }'

[
  {
    "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "scheduled_at": "2026-04-15T08:30:00Z",
    "status": "blood_drawn",
    "test_method": "practitioner",
    "created_at": "2026-04-01T09:45:00Z",
    "updated_at": "2026-04-15T08:30:00Z",
    "profile": {
      "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
      "first_name": "Maria",
      "last_name": "Schmidt",
      "email": "maria.schmidt@example.com",
      "date_of_birth": "1985-03-22",
      "sex": 2
    },
    "panels": [],
    "individual_biomarkers": [],
    "shipments": [
      {
        "id": "P2604154821",
        "added_at": "2026-04-15T08:30:00Z"
      }
    ]
  }
]

{
  "error": "Cannot attach appointments outside the allowed window — each appointment must be past blood-draw or the shipment must be less than 24 hours old. Blocked: c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a"
}

Attach one or more appointments to this shipment. Idempotent — appointments already linked are silently skipped. The mutation rule (per appointment) is: the link can be created when EITHER

the appointment is past blood-draw (blood_drawn), or
the shipment was created less than 24 hours ago.

Outside that window the call is rejected with 409 Conflict so historical records stay stable. The same rule gates Detach Appointments from Shipment and the inverse appointment-side endpoints, so partners don’t have to reason about direction.

Request

Path parameters

string

required

Shipment reference ID (e.g., P2604154821).

Body parameters

string[]

required

Array of appointment UUIDs to attach. Must contain at least one item.

Response

On success, the API returns 200 OK with the full appointment list for the shipment, oldest-link first. Each entry has the same shape as Get Appointment. Mirror of Attach Shipments to Appointment, which returns the post-mutation shipment list for the parent appointment.

Error responses

Status	Description
`400`	Validation error — e.g., empty `appointment_ids` or invalid UUID.
`403`	Forbidden — missing scope, shipment outside access context, or appointment outside access context.
`404`	Shipment not found, or one or more appointments not found.
`409`	Mutation rule failed — at least one appointment is not past blood-draw and the shipment is older than 24 hours. Response lists the IDs.
`500`	Internal server error.

curl --request POST \
  --url https://anivahealth.com/api/v1/shipments/P2604154821/appointments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "appointment_ids": [
      "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a"
    ]
  }'

[
  {
    "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "scheduled_at": "2026-04-15T08:30:00Z",
    "status": "blood_drawn",
    "test_method": "practitioner",
    "created_at": "2026-04-01T09:45:00Z",
    "updated_at": "2026-04-15T08:30:00Z",
    "profile": {
      "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
      "first_name": "Maria",
      "last_name": "Schmidt",
      "email": "maria.schmidt@example.com",
      "date_of_birth": "1985-03-22",
      "sex": 2
    },
    "panels": [],
    "individual_biomarkers": [],
    "shipments": [
      {
        "id": "P2604154821",
        "added_at": "2026-04-15T08:30:00Z"
      }
    ]
  }
]

{
  "error": "Cannot attach appointments outside the allowed window — each appointment must be past blood-draw or the shipment must be less than 24 hours old. Blocked: c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a"
}

List Shipment Appointments

Detach Appointments from Shipment

curl --request POST \
  --url https://anivahealth.com/api/v1/shipments/P2604154821/appointments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "appointment_ids": [
      "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a"
    ]
  }'

[
  {
    "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "scheduled_at": "2026-04-15T08:30:00Z",
    "status": "blood_drawn",
    "test_method": "practitioner",
    "created_at": "2026-04-01T09:45:00Z",
    "updated_at": "2026-04-15T08:30:00Z",
    "profile": {
      "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
      "first_name": "Maria",
      "last_name": "Schmidt",
      "email": "maria.schmidt@example.com",
      "date_of_birth": "1985-03-22",
      "sex": 2
    },
    "panels": [],
    "individual_biomarkers": [],
    "shipments": [
      {
        "id": "P2604154821",
        "added_at": "2026-04-15T08:30:00Z"
      }
    ]
  }
]

{
  "error": "Cannot attach appointments outside the allowed window — each appointment must be past blood-draw or the shipment must be less than 24 hours old. Blocked: c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a"
}

Health

Profiles

Appointments

Home Kit Orders

Biomarkers

Panels

Units

Locations

Documents

Shipments

Attach Appointments to Shipment

Request

Path parameters

Body parameters

Response

Error responses

​Request

​Path parameters

​Body parameters

​Response

​Error responses

Request

Path parameters

Body parameters

Response

Error responses