# Build a healthcare app

> Tutorial: use Anpheros as the medical-data backend of a healthcare app — patients, measurements, conditions, medications, documents, labs, consent, webhooks and SDKs.

Source: https://developers.anpheros.com/guides/build-a-healthcare-app

This tutorial shows how a healthcare or medical application can use Anpheros Platform as its medical-data backend: where patient records are stored, how they are read and written, how other systems are connected and how the patient stays in control. Every call below is part of the public API ([reference](https://developers.anpheros.com/docs)).

## What you are building

A typical patient-facing app — a chronic-condition tracker, a family health app, a remote-monitoring companion — needs to:

1. keep a record per patient: measurements, conditions, medications, documents;
2. show that record back as lists and a timeline;
3. accept data from other sources (devices, labs, clinics);
4. share parts of the record, with the patient's consent;
5. react when something changes.

With Anpheros your app keeps its own users, screens and business logic, and delegates the medical record to the platform:

```
Mobile / web app ──► your backend ──► Anpheros Platform API ──► FHIR R4 record of each patient
                         ▲                                              │
                         └──────────── signed webhooks ◄────────────────┘
```

Your backend holds the API key; the app talks to your backend. (Apps that act for a patient who already has an Anpheros record use OAuth instead — see step 7.)

## 1. Get a sandbox key

The sandbox is self-service: sign in with Google on the dashboard (`https://platform.anpheros.com/dashboard/`) and press *Get a sandbox key*. Sandbox keys start with `sk_test_` and can only reach the sandbox database, where your project already has its own copy of 30 synthetic patients.

```bash
export BASE=https://platform.anpheros.com
export KEY=sk_test_…
curl $BASE/v1/patients -H "Authorization: Bearer $KEY"
```

## 2. Create a patient

Each user of your app gets a patient record owned by your project.

```bash
curl -X POST $BASE/v1/patients -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{"given": "Elena", "family": "Ionescu", "birth_date": "1985-09-03", "gender": "female"}'
```

The response contains the patient `id` (your own identifier for this person — other projects see a different one) and its `fhir` reference.

## 3. Write measurements, conditions and medications

State who the data comes from with `author_type`: `patient`, `practitioner`, `device`, `import` or `ai`. If you omit it the platform records `import`, never `patient` by assumption.

```bash
# a blood-pressure reading from a connected device (LOINC panel with two components)
curl -X POST $BASE/v1/patients/$PID/observations -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -H "Idempotency-Key: $(uuidgen)" -d '{
  "code": "85354-9", "display": "Blood pressure panel", "category": "vital-signs",
  "effective_at": "2026-09-28T08:00:00Z", "author_type": "device",
  "components": [
    {"code": "8480-6", "display": "Systolic", "value": 128, "unit": "mm[Hg]"},
    {"code": "8462-4", "display": "Diastolic", "value": 82, "unit": "mm[Hg]"}
  ]}'

# a diagnosis (ICD-10 by default)
curl -X POST $BASE/v1/patients/$PID/conditions -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"code": "I10", "display": "Essential hypertension", "onset": "2024-03-01", "author_type": "practitioner"}'

# a medication (ATC by default)
curl -X POST $BASE/v1/patients/$PID/medications -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"display": "Amlodipine 5 mg", "code": "C08CA01", "dosage": "1 tablet in the morning", "start": "2024-03-01", "author_type": "patient"}'
```

Observation categories: `vital-signs`, `laboratory`, `symptom`, `activity`, `survey`, `exam`, `imaging`, `social-history`. Each write is stored as a FHIR resource and gets a `Provenance` entry automatically.

## 4. Store documents

```bash
# create the document, then upload the bytes
curl -X POST $BASE/v1/patients/$PID/documents -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"title": "Blood tests 2026-09-14", "kind": "lab_report", "content_type": "application/pdf", "date": "2026-09-14"}'
curl -X PUT $BASE/v1/documents/$DOC/content -H "Authorization: Bearer $KEY" -H 'content-type: application/pdf' --data-binary @report.pdf
```

The original is immutable after upload; values you extract from it can point back to it with `derived_from`.

## 5. Read the record back

```bash
curl "$BASE/v1/patients/$PID/observations?category=vital-signs&limit=20" -H "Authorization: Bearer $KEY"
curl "$BASE/v1/patients/$PID/medications?status=active" -H "Authorization: Bearer $KEY"
curl "$BASE/v1/patients/$PID/timeline?from=2026-06-01" -H "Authorization: Bearer $KEY"   # everything, chronologically
```

When you need the full FHIR model, the same data is available at `/fhir/R4` with the same ids ([FHIR R4 API](https://developers.anpheros.com/guides/fhir)).

## 6. Connect labs and devices

- **Lab reports:** `POST /v1/patients/{id}/labs/import` with CSV, HL7 v2 ORU^R01 or JSON turns a whole report into laboratory Observations with LOINC codes ([Lab connector](https://developers.anpheros.com/guides/lab-connector)).
- **Devices and wearables:** write Observations with `author_type: device` and the LOINC code of the measurement (heart rate, SpO₂, steps, sleep duration and others are listed in [FHIR code systems](https://developers.anpheros.com/guides/fhir-code-systems)).

## 7. Reach a record the patient already has (OAuth)

If the person already keeps a record in Anpheros (for example through Anpheros Daily), your app can ask for access instead of creating a new patient: register an application, send the person to the consent page with the scopes you need, exchange the code for tokens and call the API with the access token. The patient chooses the duration and can revoke access at any time. Details: [Authentication and OAuth](https://developers.anpheros.com/guides/authentication).

## 8. React to changes with webhooks

```bash
curl -X POST $BASE/v1/webhooks -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"url": "https://your.app/anpheros/hook", "events": ["resource.created", "consent.revoked"]}'
```

Verify the `Anpheros-Signature` header of every delivery ([Webhooks](https://developers.anpheros.com/guides/webhooks)).

## 9. Use an SDK

The same flow in TypeScript:

```ts
import { Anpheros, apiKey } from '@anpheros/sdk';

const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });
const { data: patients } = await anpheros.patients.list();
const vitals = await anpheros.observations.list(patients[0].id, { category: 'vital-signs', limit: 20 });
```

A Dart / Flutter client with the same shape is available as `anpheros_sdk` ([SDKs](https://developers.anpheros.com/guides/sdks)).

## Before going to production

- Production keys (`sk_live_`) are issued to verified organisations with a signed data processing agreement.
- Read the [Security, privacy and data residency](https://developers.anpheros.com/guides/security) page and the [limits](https://developers.anpheros.com/guides/limits).
- Handle errors by their type and quote the `Anpheros-Request-Id` header when you contact support ([Errors](https://developers.anpheros.com/guides/errors)).

## Related

- [Build with Anpheros](https://developers.anpheros.com/guides/build-with-anpheros)
- [Medical app backend and database](https://developers.anpheros.com/guides/medical-app-backend)
- [Medical data API](https://developers.anpheros.com/guides/medical-data-api)
- [Healthcare software development](https://developers.anpheros.com/guides/healthcare-software)