# Medical data API

> Where each kind of medical data goes in the Anpheros API, how it is coded, and how to write, filter, trace, correct and delete it — with working examples.

Source: https://developers.anpheros.com/guides/medical-data-api

**A medical data API gives software structured access to the contents of patient records: create a patient, record a blood-pressure reading, list active medications, attach a lab report, trace who wrote what.** This page describes the data operations of the Anpheros API — which kind of medical data goes where, how it is coded, and how to read it back — with examples that work against the sandbox.

Applications use these operations to treat Anpheros as the medical database of their product: patient records live in the platform's HL7 FHIR R4 store, and the application reads and writes them through the API instead of keeping its own tables of medical data.

For the broader picture (authentication, consent, events) see [Healthcare API](https://developers.anpheros.com/guides/healthcare-api).

## Where each kind of medical data goes

| Medical data | REST v1 | FHIR resource | Coding |
|---|---|---|---|
| The person | `POST /v1/patients` | `Patient` | name, birth date, gender, identifiers |
| Vital signs, lab results, symptoms, activity, surveys | `/v1/patients/{id}/observations` | `Observation` | LOINC (symptoms: ICD-10 chapter R); UCUM units |
| Diagnoses and problems | `/v1/patients/{id}/conditions` | `Condition` | ICD-10 |
| Medications | `/v1/patients/{id}/medications` | `MedicationStatement` | ATC, product name kept as text |
| Documents (PDF, images) | `/v1/patients/{id}/documents` | `DocumentReference` | LOINC document kinds |
| A whole lab report | `POST /v1/patients/{id}/labs/import` | `Observation` (laboratory) | LOINC where known, the lab's own code otherwise |
| Doses taken or skipped, vaccinations, allergies, procedures, reports, care plans, goals, referrals, visits, appointments, care teams, family history, questionnaires | `/fhir/R4/{type}` | `MedicationAdministration`, `Immunization`, `AllergyIntolerance`, `Procedure`, `DiagnosticReport`, `CarePlan`, `Goal`, `ServiceRequest`, `Encounter`, `Appointment`, `CareTeam`, `FamilyMemberHistory`, `QuestionnaireResponse` | per [FHIR code systems](https://developers.anpheros.com/guides/fhir-code-systems) |

REST v1 objects and FHIR resources are the same records with the same ids; every v1 object carries its `fhir` reference.

## Writing medical data

```bash
# a lab result with its reference range, linked to the report it came from
curl -X POST https://platform.anpheros.com/v1/patients/$PID/observations \
     -H "Authorization: Bearer $KEY" -H 'content-type: application/json' -H "Idempotency-Key: $(uuidgen)" -d '{
  "code": "4548-4", "display": "Hemoglobin A1c", "category": "laboratory",
  "value": 6.4, "unit": "%", "effective_at": "2026-09-01T08:00:00Z",
  "reference_range": {"low": 4.0, "high": 5.6},
  "derived_from": ["DocumentReference/'$DOC'"], "author_type": "import"
}'
```

- **Observation categories:** `vital-signs`, `laboratory`, `symptom`, `activity`, `survey`, `exam`, `imaging`, `social-history`.
- **Composite measurements** such as blood pressure use `components` (systolic `8480-6`, diastolic `8462-4` inside the panel `85354-9`).
- **Author types:** `patient`, `practitioner`, `device`, `import`, `ai`. Without one, the platform records `import`.
- **Codes you do not know by heart:** `GET /v1/terminology/loinc?q=hba1c` and `GET /v1/terminology/atc?q=metformin` search the bundled code subsets; an observation written without a display name gets the LOINC name automatically.

## Reading medical data

```bash
curl "https://platform.anpheros.com/v1/patients/$PID/observations?category=laboratory&code=4548-4&from=2026-01-01" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/conditions?clinical_status=active" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/medications?status=active" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/timeline?from=2026-06-01" -H "Authorization: Bearer $KEY"
```

| Endpoint | Filters |
|---|---|
| observations | `category`, `code`, `from`, `to` |
| conditions | `clinical_status` |
| medications | `status` |
| documents | `kind` |
| timeline | `from`, `to`, `types` |

Lists are paged with `limit` and `cursor`. The **timeline** merges observations, conditions, medications, documents, visits, appointments, vaccinations and episodes of care into one chronological list — the natural input for a patient history screen.

For anything the REST filters do not cover, use FHIR search: `GET /fhir/R4/Observation?patient=$PID&code=http://loinc.org|4548-4&_sort=-date` ([FHIR platform](https://developers.anpheros.com/guides/fhir)).

## Tracing and correcting data

- **Who wrote it:** `GET /v1/patients/{id}/provenance/{type}/{resourceId}` — one entry per version, with author type, project, organisation and source system.
- **Every version:** `GET /fhir/R4/{type}/{id}/_history`; update with `If-Match` to avoid overwriting someone else's change.
- **Ownership:** with consent you can read what other organisations wrote, but change or delete only what your project wrote (`403` otherwise).
- **Deletion:** `DELETE /v1/{observations|conditions|medications}/{id}`; deleting a `Patient` deletes the whole record.

## Documents

Create the document (you get an upload target), upload the bytes through the platform or directly to storage, then finalise. After finalisation the original is immutable; its SHA-256 and size are recorded. Up to 25 MiB per file.

## Related

- [Healthcare API](https://developers.anpheros.com/guides/healthcare-api)
- [Patient medical record](https://developers.anpheros.com/guides/patient-medical-record)
- [Build a healthcare app](https://developers.anpheros.com/guides/build-a-healthcare-app)
- [API reference (OpenAPI)](https://developers.anpheros.com/docs) · [Getting started](https://developers.anpheros.com/guides/getting-started)