Quick Start

This guide walks you through the core workflow: finding a test location, creating a patient profile, scheduling an appointment, and confirming a blood draw.

Prerequisites

You need a partner API key issued by Aniva.

If you don’t have an API key yet, contact Aniva to get one issued for your partner account.

Steps

List available locations

Retrieve the list of test locations to find a location_id for the appointment you will schedule.

curl https://anivahealth.com/api/v1/locations \
  -H "x-api-key: YOUR_API_KEY"

Example response

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Aniva Berlin Mitte",
    "company_name": "Aniva GmbH",
    "street": "Unter den Linden",
    "house_number": "42",
    "address_line_2": null,
    "city": "Berlin",
    "state": "Berlin",
    "postal_code": "10117",
    "country_name": "Germany",
    "country_code": "DE",
    "timezone": "Europe/Berlin",
    "contact_phone": "+4930987654321",
    "email": "berlin-mitte@anivahealth.com",
    "website": "https://anivahealth.com",
    "google_maps_url": null,
    "image_url": null,
    "open_hours": {
      "monday": [{ "open": "08:00", "close": "18:00" }],
      "tuesday": [{ "open": "08:00", "close": "18:00" }],
      "wednesday": [{ "open": "08:00", "close": "18:00" }],
      "thursday": [{ "open": "08:00", "close": "18:00" }],
      "friday": [{ "open": "08:00", "close": "16:00" }],
      "saturday": [],
      "sunday": []
    }
  }
]

Note the id of the location you want to use. You will need it in step 3.

Create a profile

Create a patient profile by sending their demographic data. The profile_group ties the profile to your partner account — it accepts either the group’s immutable UUID or its human-readable slug.

curl -X POST https://anivahealth.com/api/v1/profiles \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jordan",
    "last_name": "Rivera",
    "sex": 1,
    "date_of_birth": "1990-04-15",
    "profile_group": "your-profile-group"
  }'

Request body fields

Field	Type	Required	Description
`first_name`	string	Yes	Patient’s first name
`last_name`	string	Yes	Patient’s last name
`sex`	integer	Yes	`1` = male, `2` = female (ISO/IEC 5218)
`date_of_birth`	string	Yes	Date of birth in `YYYY-MM-DD` format. Must be in the past, not before 1900, and imply an age of 16–100.
`profile_group`	string	Yes*	UUID or slug of your partner profile group. UUID is the stable reference; slug is also accepted.
`profile_group_slug`	string	No	Deprecated. Slug alias for `profile_group`. Either `profile_group` or `profile_group_slug` is required.
`email`	string	No	Patient email. Auto-generated if omitted.
`language`	string	No	`en`, `de`, or `fi`. Defaults to `en`.
`phone`	string	No	Phone number in E.164 format, for example `+4915123456789`.
`height`	number	No	Height in centimeters.
`weight`	number	No	Weight in kilograms.
`transactional_emails_enabled`	boolean	No	Overrides the profile group default for operational emails.
`marketing_emails_enabled`	boolean	No	Overrides the profile group default for marketing emails.

Example response (201 Created)

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "handle": null,
  "first_name": "Jordan",
  "last_name": "Rivera",
  "email": "jordan.rivera@example.com",
  "phone": null,
  "sex": 1,
  "date_of_birth": "1990-04-15",
  "height": null,
  "weight": null,
  "language": "en",
  "transactional_emails_enabled": null,
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": null
}

Note the id from the response. You will use it as profile_id in the next step.

Schedule an appointment

Create an appointment using the profile_id from step 2 and the location_id from step 1. Set scheduled_at to a slot start that Get availability returns for that location. The API rejects a time that is not on the slot grid.

curl -X POST https://anivahealth.com/api/v1/appointments \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "location_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scheduled_at": "2026-04-10T09:00:00Z"
  }'

Example response (201 Created)

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "profile_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "location_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scheduled_at": "2026-04-10T09:00:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "created_at": "2026-04-01T10:05:00Z",
  "updated_at": null,
  "profile": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "handle": null,
    "first_name": "Jordan",
    "last_name": "Rivera",
    "email": "jordan.rivera@example.com",
    "phone": null,
    "sex": 1,
    "date_of_birth": "1990-04-15",
    "height": null,
    "weight": null,
    "language": "en",
    "transactional_emails_enabled": null,
    "created_at": "2026-04-01T10:00:00Z",
    "updated_at": null
  },
  "panels": [],
  "individual_biomarkers": [],
  "shipments": [],
  "lab_codes": []
}

Note the appointment id. You will use it to confirm the blood draw.

Confirm the blood draw

After the blood draw is complete, submit the lab code (tube barcode) to confirm the draw and trigger the lab order pipeline. A draw whose tubes carry several codes sends lab_codes instead — see Confirm Blood Draw.

curl -X POST https://anivahealth.com/api/v1/appointments/c3d4e5f6-a7b8-9012-cdef-123456789012/confirm \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lab_code": "7642001234"
  }'

Example response (200 OK)

{
  "success": true
}

Once confirmed, the lab order pipeline is triggered. You can retrieve the appointment to verify its status has changed to "blood_drawn".

Next steps

Add panels to an appointment to specify which lab tests to run.
Update an appointment to reschedule or change location before blood draw.
Cancel an appointment if it is no longer needed.
Get lab results to retrieve clinical and genetic results after processing.
Download documents to fetch lab report PDFs.
Retrieve a profile to check or display patient data.
Review the full API Reference for all available endpoints and parameters.

Get Started

Core Concepts

Guides

Prerequisites

Steps

Next steps

​Prerequisites

​Steps

​Next steps

Prerequisites

Steps

Next steps