List Appointments

GET

api

appointments

curl --request GET \
  --url https://anivahealth.com/api/v1/appointments \
  --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
  --url 'https://anivahealth.com/api/v1/appointments?profile_id=a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d' \
  --header 'x-api-key: YOUR_API_KEY'

[
  {
    "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "scheduled_at": "2026-05-15T10:30:00Z",
    "status": "confirmed",
    "cancellation_reason": null,
    "results_ready_emails": [],
    "created_at": "2026-04-01T09:45:00Z",
    "updated_at": null,
    "profile": {
      "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
      "handle": null,
      "first_name": "Maria",
      "last_name": "Schmidt",
      "email": "maria.schmidt@example.com",
      "phone": "+4930123456789",
      "sex": 2,
      "date_of_birth": "1985-03-22",
      "height": 168,
      "weight": 65,
      "language": "de",
      "transactional_emails_enabled": true,
      "created_at": "2026-04-01T09:14:32Z",
      "updated_at": null
    },
    "panels": [
      {
        "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
        "added_at": "2026-04-01T09:50:00Z"
      }
    ],
    "individual_biomarkers": [
      {
        "biomarker_id": 42,
        "added_at": "2026-04-01T09:52:00Z"
      }
    ],
    "shipments": [
      {
        "id": "P2604154821",
        "added_at": "2026-04-15T07:00:00Z"
      }
    ],
    "lab_codes": []
  }
]

{
  "error": "Access denied: profile is outside your permission scope"
}

Retrieve a list of blood draw appointments. Each appointment includes the embedded patient profile. When profile_id is provided, returns all appointments for that profile with no time restriction. When omitted, returns all accessible appointments within a default time window (past 2 months to future 1 month). Requires the test_sessions_view or test_sessions_schedule scope.

Request

Query parameters

string

Filter by profile UUID. When provided, all appointments for this profile are returned regardless of scheduling date. When omitted, the default time window applies.

Response

On success, the API returns 200 OK with an array of appointment objects.

string

required

Unique appointment identifier (UUID).

string

required

UUID of the profile this appointment belongs to.

string

UUID of the test location where the draw takes place.

string

Scheduled appointment datetime as a UTC instant (ISO 8601 with Z suffix, e.g. 2026-05-15T10:30:00Z). May be null.

string

required

Current appointment status. One of pending, confirmed, blood_drawn, or cancelled. Lab-result completion granularity is derived from Get Results; finer-grained shipment progression from each entry in the inline shipments array (see below) followed to Get Shipment.

string

Free-text reason captured when the appointment was cancelled (e.g. no-show, late cancellation, ‘Failed. Repeat required’). null unless status is cancelled.

string[]

required

Addresses that each get one email once every lab result is final, lowercased. Empty when off. See Results-ready emails.

string

required

ISO 8601 timestamp of when the appointment was created.

string

ISO 8601 timestamp of the last update. May be null.

object

required

The patient profile associated with this appointment.

Show profile

string

Unique profile identifier (UUID).

string

Profile handle or username. May be null.

string

First name. May be null.

string

Last name. May be null.

string

Email address. May be null.

string

Phone number in E.164 format. May be null.

integer

Biological sex per ISO/IEC 5218. May be null.

string

Date of birth in YYYY-MM-DD format. May be null.

number

Height in centimeters. May be null.

number

Weight in kilograms. May be null.

string

Preferred language (en, de, or fi).

boolean

Whether this profile receives transactional (programmatic) emails. May be null.

string

ISO 8601 timestamp of when the profile was created.

string

ISO 8601 timestamp of the last profile update. May be null.

AppointmentPanel[]

required

Panels currently attached to this appointment. Excludes cancelled attachments. Look up panel details (name, biomarkers) via List Panels.

Show Panel attachment fields

string

Panel UUID — cross-reference against List Panels.

string

ISO 8601 timestamp the panel was first attached to this appointment.

AppointmentIndividualBiomarker[]

required

À-la-carte biomarkers attached to this appointment outside any panel (see Add Custom Biomarkers). Cross-reference each biomarker_id against List Biomarkers for display data.

Show Individual biomarker fields

integer

Biomarker identifier — cross-reference against List Biomarkers.

string

ISO 8601 timestamp the biomarker was first attached to this appointment.

AppointmentShipmentLink[]

required

Shipments linked to this appointment, oldest-link first. Empty array when no shipments are linked. Cross-reference each id against Get Shipment for the full shipment payload (status, tracking number, status updates, etc.).

Show Shipment link fields

string

Shipment reference identifier — cross-reference against Get Shipment.

string

ISO 8601 timestamp the shipment was first linked to this appointment.

string[]

required

Lab codes (tube barcodes) recorded for this appointment, in scan order. Empty until the blood draw is confirmed. A venous draw carries one code printed on every tube; a pharmacy draw carries one code per microtainer. Results and documents on Get Results reference these codes via lab_code.

Error responses

Status	Description
`403`	Forbidden — your API key does not have access to this operation, or the requested profile is outside your permission scope.
`500`	Internal server error.

curl --request GET \
  --url https://anivahealth.com/api/v1/appointments \
  --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
  --url 'https://anivahealth.com/api/v1/appointments?profile_id=a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d' \
  --header 'x-api-key: YOUR_API_KEY'

[
  {
    "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "scheduled_at": "2026-05-15T10:30:00Z",
    "status": "confirmed",
    "cancellation_reason": null,
    "results_ready_emails": [],
    "created_at": "2026-04-01T09:45:00Z",
    "updated_at": null,
    "profile": {
      "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
      "handle": null,
      "first_name": "Maria",
      "last_name": "Schmidt",
      "email": "maria.schmidt@example.com",
      "phone": "+4930123456789",
      "sex": 2,
      "date_of_birth": "1985-03-22",
      "height": 168,
      "weight": 65,
      "language": "de",
      "transactional_emails_enabled": true,
      "created_at": "2026-04-01T09:14:32Z",
      "updated_at": null
    },
    "panels": [
      {
        "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
        "added_at": "2026-04-01T09:50:00Z"
      }
    ],
    "individual_biomarkers": [
      {
        "biomarker_id": 42,
        "added_at": "2026-04-01T09:52:00Z"
      }
    ],
    "shipments": [
      {
        "id": "P2604154821",
        "added_at": "2026-04-15T07:00:00Z"
      }
    ],
    "lab_codes": []
  }
]

{
  "error": "Access denied: profile is outside your permission scope"
}

curl --request GET \
  --url https://anivahealth.com/api/v1/appointments \
  --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
  --url 'https://anivahealth.com/api/v1/appointments?profile_id=a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d' \
  --header 'x-api-key: YOUR_API_KEY'

[
  {
    "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "scheduled_at": "2026-05-15T10:30:00Z",
    "status": "confirmed",
    "cancellation_reason": null,
    "results_ready_emails": [],
    "created_at": "2026-04-01T09:45:00Z",
    "updated_at": null,
    "profile": {
      "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
      "handle": null,
      "first_name": "Maria",
      "last_name": "Schmidt",
      "email": "maria.schmidt@example.com",
      "phone": "+4930123456789",
      "sex": 2,
      "date_of_birth": "1985-03-22",
      "height": 168,
      "weight": 65,
      "language": "de",
      "transactional_emails_enabled": true,
      "created_at": "2026-04-01T09:14:32Z",
      "updated_at": null
    },
    "panels": [
      {
        "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
        "added_at": "2026-04-01T09:50:00Z"
      }
    ],
    "individual_biomarkers": [
      {
        "biomarker_id": 42,
        "added_at": "2026-04-01T09:52:00Z"
      }
    ],
    "shipments": [
      {
        "id": "P2604154821",
        "added_at": "2026-04-15T07:00:00Z"
      }
    ],
    "lab_codes": []
  }
]

{
  "error": "Access denied: profile is outside your permission scope"
}

Health

Profiles

Appointments

Home Kit Orders

Biomarkers

Panels

Pricing

Units

Locations

Documents

Shipments

Webhooks

Request

Query parameters

Response

Error responses

​Request

​Query parameters

​Response

​Error responses

Request

Query parameters

Response

Error responses