Patients and episodes

A patient is the person a visit is about. An episode is a reason that groups several visits for that person.

Tiep keeps a light registry of both, so consultations can be grouped and looked up later.

Why they exist

Tiep is not the hospital system. The hospital still owns the real patient record.

Tiep only keeps enough to answer two questions:

• Which visits belong to the same person?
• Which visits belong to the same reason?

So the registry is small on purpose. Every descriptive field is optional except one id.

The patient

A patient always has an internal_id. That is the facility's own readable id (the same one the hospital already uses).

Everything else is optional.

{
  "internal_id": "MRN-12345",
  "name": "Anna",
  "lastname": "Smith",
  "alias": "Room 4",
  "id_number": "X1234567Z",
  "phone": "+34 600 000 000",
  "email": "[email protected]",
  "address": "123 Test St"
}

Rules:

• internal_id is required and unique inside the facility.
• Two facilities may reuse the same internal_id without clashing.
• If a patient is deleted, that internal_id becomes free again.

The episode

An episode groups visits under one reason, like "Knee rehab 2026".

There are two kinds, for two different people:

Kind	Who creates it	Main fields
Doctor episode	A doctor, from the app	title, description
Integration episode	The hospital system, by API	external_id (+ optional title)

The external_id is just a matching key for integrations. Doctors never see it or need it.

Rules:

• An episode may belong to one patient, or to none yet.
• An episode always belongs to the same facility as its patient.
• external_id is unique per facility, so the same hospital episode is never created twice — resending it matches the existing one instead.
• Doctor episode titles do not have to be unique.

The registry is optional

First, the plan must allow patients and episodes at all. If it doesn't, the whole feature is locked: the patient page and settings are read-only, doctors don't see the patient panel, and the backend never saves a patient. Existing data is kept untouched — it simply can't be viewed or changed until the plan allows it again.

When the plan allows it, a new facility still starts with the registry off. No patient data is stored until it opts in.

A facility then turns on only what it needs:

Setting	What it allows
use_patient_registry	Store patients and episodes at all.
doctors_can_set_patient	A doctor may pick the patient for a visit.
doctors_can_set_episode	A doctor may pick or create the episode.
doctors_can_view_others_consultations	A doctor may see other doctors' visits in a patient's history.

If the registry is off, visits still work. They just are not grouped.

Where the link lives

The link belongs to the session, not to the consultation.

A doctor entering the canvas does not create anything. The link is fixed when the session starts, and the consultation inherits it.

How a patient gets attached

A visit can learn its patient from three places:

1. Doctor selection — only if doctors_can_set_patient is on.
2. Situation context — patient/episode data sent with the visit (FHIR or the simple shape).
3. Generated token — the hospital names the patient when it creates the login token.

What can change, and when

The patient is fixed once the session starts. It is the who, and the who does not change.

The episode is gentler:

• If a patient has no episode yet, a doctor may add one (when allowed).
• Once an episode is set, it cannot be replaced.
• Once the visit has any saved report, nothing can change.

Privacy modes

Readable patient info (name, contact, episode title) can be stored three ways. The facility chooses one mode with patient_data_mode.

Mode	What the server stores	Who can read it
none	Only the internal_id (and a plain alias).	Nobody stores names.
plaintext	Names encrypted at rest with a server key.	The server, to show them back.
encrypted	Only ciphertext the browser produced.	Only a browser with the facility key.

In encrypted mode the server is blind. The passphrase and key never leave the browser, so even Tiep cannot read the names.

The internal_id is always readable, in every mode.

Patient history

A patient's history has three simple parts:

• The list of episodes.
• The visits inside an episode.
• The visits with no episode.

By default a doctor sees only their own visits. With doctors_can_view_others_consultations, they see the whole facility's visits for that patient.

Deleting a patient

Deleting a patient removes the identity, not the medicine.

• The consultation reports stay.
• Episodes stay, but lose their patient link.
• The internal_id becomes free to reuse.

API examples

Create a patient from the hospital system:

curl -X POST "https://api.tiep.ai/v1/facilities/{facility_id}/patients" \
  -H "X-API-Key: $FACILITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "internal_id": "MRN-12345",
    "name": "Anna",
    "lastname": "Smith"
  }'

Create an integration episode for that patient:

curl -X POST "https://api.tiep.ai/v1/facilities/{facility_id}/episodes" \
  -H "X-API-Key: $FACILITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "EP-2026-KNEE",
    "patient_id": 42,
    "title": "Knee rehab 2026"
  }'

Name the patient and episode when generating a login token:

curl -X POST "https://api.tiep.ai/v1/auth/generate-token" \
  -H "X-API-Key: $FACILITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "doctor": { "id": "doctor-123" },
    "patient": { "internal_id": "MRN-12345" },
    "episode": { "external_id": "EP-2026-KNEE" }
  }'

The token response includes a session_id. That session is already linked to the patient and episode, so the visit is grouped from the start.

Read the end-to-end example for the whole launch flow.