encounter

A patient visit or stay. encounter records reach the canonical layer from two distinct origins, distinguishable by patientRef.sourceSystem (and by which identifiers system is present):

• Provider-origin — an inpatient admission or outpatient appointment reported by the FHIR provider itself (patientRef.sourceSystem is the provider's source system, e.g. "michels"; identifiers[].system is urn:michels:encounter). This is the original behavior of this resource type.
• Rosetta-app-origin — a therapy case's admission/discharge dates, captured in rosetta-app and synced into the canonical layer (patientRef.sourceSystem is "rosetta-app"; identifiers[].system is urn:rosetta-app:therapy-case). One canonical encounter exists per (patient, discipline) therapy case — it is generated the moment rosetta-app records an admission date for that case, and is updated in place (not replaced) as the discharge date is later added. Other resource types such as condition and procedure may optionally reference either kind of encounter via encounterRef.

Fields

Field	Type	Required	Description
identifiers	Identifier[]	no (defaults [])	Business identifiers, e.g. a visit number, or the rosetta-app case key.
patientRef	SourceRef	yes	The patient this encounter belongs to.
status	string enum	yes	One of planned, in-progress, finished, cancelled, unknown.
classCode	string	no	Source-provided encounter class, e.g. AMB (ambulatory), IMP (inpatient).
periodStart	IsoDatetime	no	When the encounter started.
periodEnd	IsoDatetime	no	When the encounter ended.

classCode is provider-origin only — rosetta-app-origin encounters never set it (the formData-free rosetta-app source has no equivalent column); do not treat its absence as missing data on that origin.

Example payload — provider-origin

An outpatient visit reported by the FHIR provider:

{
  "identifiers": [{ "system": "urn:michels:encounter", "value": "ENC-2001" }],
  "patientRef": {
    "sourceSystem": "michels",
    "resourceType": "patient",
    "sourceId": "pat-1"
  },
  "status": "finished",
  "classCode": "IMP",
  "periodStart": "2026-07-10T08:30:00.000Z",
  "periodEnd": "2026-07-12T11:00:00.000Z"
}

Example payload — rosetta-app-origin (therapy case)

A physiotherapy case in rosetta-app, right after admission — only the admission date is known, so status is in-progress and periodEnd is absent:

{
  "identifiers": [
    { "system": "urn:rosetta-app:therapy-case", "value": "pat-42:physiotherapy" }
  ],
  "patientRef": {
    "sourceSystem": "rosetta-app",
    "resourceType": "patient",
    "sourceId": "pat-42"
  },
  "status": "in-progress",
  "periodStart": "2026-07-01T00:00:00.000Z"
}

When the same case is later discharged, rosetta-app updates this same canonical record in place — a new version, the same canonicalId — rather than creating a second encounter:

{
  "identifiers": [
    { "system": "urn:rosetta-app:therapy-case", "value": "pat-42:physiotherapy" }
  ],
  "patientRef": {
    "sourceSystem": "rosetta-app",
    "resourceType": "patient",
    "sourceId": "pat-42"
  },
  "status": "finished",
  "periodStart": "2026-07-01T00:00:00.000Z",
  "periodEnd": "2026-07-10T00:00:00.000Z"
}

periodStart/periodEnd on this origin come from rosetta-app's admitted_at/ discharged_at date columns (no time-of-day component), composed as clinic-local midnight normalized to UTC — treat them as date-precision, not a true visit start/end time.

As a change-feed event

The discharge update above, as it arrives on the change feed (operation: "update", version: 2 — the same canonicalId as the case's admission event, version: 1):

{
  "sequence": 214,
  "resourceType": "encounter",
  "canonicalId": "6a1e4c8d-2b5f-4a9c-8d1e-4c8b2f5a9d1e",
  "operation": "update",
  "version": 2,
  "occurredAt": "2026-07-10T00:00:05.000Z",
  "orgSlug": "default",
  "record": {
    "identifiers": [
      { "system": "urn:rosetta-app:therapy-case", "value": "pat-42:physiotherapy" }
    ],
    "patientRef": {
      "sourceSystem": "rosetta-app",
      "resourceType": "patient",
      "sourceId": "pat-42"
    },
    "status": "finished",
    "periodStart": "2026-07-01T00:00:00.000Z",
    "periodEnd": "2026-07-10T00:00:00.000Z"
  }
}

From the Records API

curl -H "Authorization: Bearer $ROSETTA_SYNC_TOKEN" \
  "https://sync.example.com/api/v1/records/encounter/6a1e4c8d-2b5f-4a9c-8d1e-4c8b2f5a9d1e"

{
  "id": "6a1e4c8d-2b5f-4a9c-8d1e-4c8b2f5a9d1e",
  "resourceType": "encounter",
  "version": 2,
  "payload": {
    "identifiers": [
      { "system": "urn:rosetta-app:therapy-case", "value": "pat-42:physiotherapy" }
    ],
    "patientRef": {
      "sourceSystem": "rosetta-app",
      "resourceType": "patient",
      "sourceId": "pat-42"
    },
    "status": "finished",
    "periodStart": "2026-07-01T00:00:00.000Z",
    "periodEnd": "2026-07-10T00:00:00.000Z"
  },
  "updatedAt": "2026-07-10T00:00:05.000Z",
  "orgSlug": "default",
  "identifiers": [
    { "system": "urn:rosetta-app:therapy-case", "value": "pat-42:physiotherapy" }
  ]
}

Consumption notes

• status is a lifecycle enum; treat unknown (and any value your integration doesn't recognize yet) defensively rather than assuming it means the encounter is over. Rosetta-app-origin encounters only ever produce in-progress (admitted, not yet discharged) or finished (discharged) — never planned, cancelled, or unknown.
• periodStart/periodEnd are normalized timestamps — always Z-suffixed UTC regardless of the offset the source system reported.
• classCode is a source-provided class string (e.g. AMB, IMP) — treat it as free text from the source system rather than a fixed enum you validate against, and expect it to be absent on rosetta-app-origin records (see Fields above).
• Rosetta-app-origin encounter records are an aggregate keyed on the (patient, discipline) case, updated in place as admission/discharge dates change — the same pattern as observation and care-plan. Always overwrite your stored copy on a new event rather than merging fields, and dedupe applied events on (canonicalId, version).
• A therapy case's completed admission/discharge forms are separate records — admission and discharge — correlate them to their case's encounter by matching patientRef and discipline, not by any shared id (the form records carry their own row identity; encounter's identity is the case).
• patientRef is a source reference; correlate it to the canonical patient whose identifiers contain the matching business identifier.