# Longitudinal patient data API

> One patient's history over time from clinics, labs, apps and devices: what a longitudinal record needs, and four ways to read it — timeline, $everything, IPS and AI context.

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

**A longitudinal patient data API returns one person's health history over time — diagnoses, medications, lab results, vital signs, vaccinations and visits from every source — as one ordered record instead of separate documents per provider.** Anpheros keeps that history as a single HL7 FHIR R4 record per patient, written by clinics, laboratories, apps and devices, with every version and every author kept. Developers read it four ways: a chronological timeline, the full FHIR record with `Patient/$everything`, an International Patient Summary, or a compact context for AI models.

<!-- visual:longitudinal-sources -->

## What "longitudinal" requires

A list of results is not yet a longitudinal record. For an application to trust a history that spans years and providers, each entry has to carry:

| Requirement | Why it matters | How Anpheros stores it |
|---|---|---|
| A coded meaning | Values from different labs must be comparable | LOINC for results, ICD-10 for conditions, ATC for medications |
| A clinical date | Ordering by when it happened, not when it was uploaded | `effective`, `onset`, `occurrence` dates on each resource |
| The author | A doctor's diagnosis and a patient's note are not equal | Provenance on every write: author type, person, organisation, source system |
| Every version | Corrections must not erase what was known before | Version history on every resource (`_history`) |
| Consent | Other applications see the history only if the person agrees | OAuth grants with scopes, expiry and an access log |

## One record, many writers

<!-- visual:longitudinal-timeline -->

## Four ways to read the history

| Need | Endpoint | What you get |
|---|---|---|
| A chronological feed for a screen | `GET /v1/patients/{id}/timeline` | Items of eight types (observation, condition, medication, document, encounter, appointment, immunization, episode) with date, title, summary and the FHIR reference; filter with `from`, `to`, `types` |
| The complete record as FHIR | `GET /fhir/R4/Patient/{id}/$everything` | A searchset Bundle; `_since`, `_type`, `_count` and `_offset` are supported |
| A shareable clinical summary | `GET /fhir/R4/Patient/{id}/$summary` | An International Patient Summary (IPS) document |
| Input for an AI model | `POST /v1/context` | Sections within a token budget, each fact labelled with its source |

The timeline with the TypeScript SDK:

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

const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });   // a sandbox key, sk_test_…
const { data: patients } = await anpheros.patients.list();
const page = await anpheros.timeline.list(patients[0].id, {
  from: '2025-01-01',
  types: 'condition,medication,observation',
  limit: 50,
});
for (const item of page.data) console.log(item.date, item.type, item.title);
```

And the same record as FHIR, limited to what changed since a date:

```bash
curl -H "Authorization: Bearer $ANPHEROS_KEY" \
  "https://platform.anpheros.com/fhir/R4/Patient/$PATIENT/\$everything?_since=2026-01-01&_type=Observation,Condition"
```

## Keeping your copy in sync

If your application keeps its own view of the history, subscribe to `resource.created`, `resource.updated` and `resource.deleted` webhooks. They also fire when another project writes into a record you have access to, with `data.external: true` and the writer in `data.source`, so data from other clinics reaches you without polling.

## Limits worth knowing

- The record holds what was written into it. Anpheros does not fetch history from hospitals or national networks on its own; clinics, labs, apps and the person write it.
- 26 FHIR R4 resource types are stored. Billing resources such as Claim and ExplanationOfBenefit are not.
- Other applications read a person's history only under that person's consent; a project's own key sees the patients it created.

## Frequently asked questions

### What is longitudinal patient data?
A person's health information collected over time and across care settings — diagnoses, medications, results, vital signs, vaccinations and visits — kept so it can be read as one continuous history.

### Which API gives a chronological view of a patient's record?
In Anpheros, `GET /v1/patients/{id}/timeline` returns entries from eight resource types in date order, with paging and date and type filters. For the full FHIR data use `Patient/$everything`.

### Is the history stored in a standard format?
Yes. Every entry is an HL7 FHIR R4 resource with standard codes (LOINC, ICD-10, ATC, CVX, UCUM), and the summary is an International Patient Summary.

### How do I know who wrote each entry?
Every write creates a Provenance resource with the author type (patient, practitioner, device, import or AI), the person, the organisation and the source system.

### Can I test with realistic longitudinal data?
Yes. Every sandbox project starts with 30 synthetic patients with about six months of conditions, medications, laboratory results and vital signs.

<!-- visual:cta-longitudinal -->

## Related

- [Personal health record (PHR) app with FHIR](https://developers.anpheros.com/guides/personal-health-record-app): a timeline in a real app
- [Medical data provenance explained](https://developers.anpheros.com/guides/medical-data-provenance)
- [Patient consent platform for health apps](https://developers.anpheros.com/guides/patient-consent-platform)
- [How to store medical records using FHIR R4](https://developers.anpheros.com/guides/store-medical-records-fhir)
- [AI agents and medical data](https://developers.anpheros.com/guides/ai-agents-medical-data): the context endpoint
- [Webhooks](https://developers.anpheros.com/guides/webhooks)