patient

The core demographic record every other canonical resource type references, via a source reference such as patientRef. It originates from the provider's patient registry and is typically the first resource type an integration reads.

Fields

Field	Type	Required	Description
identifiers	Identifier[]	yes (≥1)	Business identifiers, e.g. an MRN; used for ?identifier= lookups.
familyName	string	no	Family (last) name.
givenNames	string[]	no (defaults [])	Given (first/middle) names, in order.
birthDate	string (YYYY-MM-DD date)	no	Date of birth. A plain date, not a timestamp.
gender	string enum	no	One of male, female, other, unknown.
deceased	boolean	no	Whether the patient is recorded as deceased.

Example payload

{
  "identifiers": [{ "system": "urn:michels:pid", "value": "1234567" }],
  "familyName": "Mueller",
  "givenNames": ["Anna"],
  "birthDate": "1980-05-01",
  "gender": "female",
  "deceased": false
}

As a change-feed event

{
  "sequence": 1,
  "resourceType": "patient",
  "canonicalId": "f3024f2e-0583-4759-a9b8-c534e6763391",
  "operation": "create",
  "version": 1,
  "occurredAt": "2026-07-14T04:32:56.082Z",
  "orgSlug": "default",
  "record": {
    "identifiers": [{ "system": "urn:michels:pid", "value": "1234567" }],
    "familyName": "Mueller",
    "givenNames": ["Anna"],
    "birthDate": "1980-05-01",
    "gender": "female",
    "deceased": false
  }
}

From the Records API

curl -H "Authorization: Bearer $ROSETTA_SYNC_TOKEN" \
  "https://sync.example.com/api/v1/records/patient/f3024f2e-0583-4759-a9b8-c534e6763391"

{
  "id": "f3024f2e-0583-4759-a9b8-c534e6763391",
  "resourceType": "patient",
  "version": 1,
  "payload": {
    "identifiers": [{ "system": "urn:michels:pid", "value": "1234567" }],
    "familyName": "Mueller",
    "givenNames": ["Anna"],
    "birthDate": "1980-05-01",
    "gender": "female",
    "deceased": false
  },
  "updatedAt": "2026-07-14T04:32:56.082Z",
  "orgSlug": "default",
  "identifiers": [{ "system": "urn:michels:pid", "value": "1234567" }]
}

You can also look this record up by business identifier instead of canonical id: GET /api/v1/records/patient?identifier=urn:michels:pid|1234567.

Consumption notes

• patient is the hub record every other resource type points at via patientRef (a source reference). Resolve a patientRef to a canonical patient by matching business identifiers, not by assuming any id shape.
• Use the ?identifier=<system>|<value> point-lookup pattern on the Records API when you already know a patient's business identifier and don't want to scan the change feed.
• givenNames may be an empty array — do not assume at least one given name is present.
• birthDate is a plain YYYY-MM-DD date string, not a normalized timestamp — there is no time-of-day or timezone component to reason about.