Patient & Encounter resource groups

Every FHIR Extraction response contains exactly one Patient and one Encounter, always as the first two entries of the Bundle. They give the clinical resources their context: whose record they belong to, and which visit produced them. You cannot turn them off. They follow the FHIR R4 Patient and FHIR R4 Encounter specifications, and each field name below links to its R4 definition. The endpoint can fill both resources from the note, but your system usually knows these values better than the note does. Send them in the patient and encounter request fields: each value you send replaces what the endpoint reads from the note. Reduce extraction errors shows which mistakes this avoids.

What the endpoint reads from the note

For any value you do not send, the endpoint looks for it in the note. It fills a field only when the note states the value directly, and does not infer one:

It reads “male”, “female”, “M”, or “F” as the gender, but does not infer gender from a name.
It reads a stated date of birth, such as “DOB: 1968-04-02”, but does not calculate one from an age.
It reads “ED” as emergency and “admitted to ward” as inpatient, but does not infer the setting from the type of note.
It reads “admitted” as in-progress and “discharged” as finished. Without such a word, status stays in-progress.
It reads a time of day only together with a timezone. A time without one is cut back to its date, because R4 accepts a time only with a timezone offset.
It reads admission and discharge dates for period, but ignores dates that belong to other events, such as the date of a past operation.

When the note states nothing about the patient, the Patient resource holds only its id and identifier. When the note states nothing about the encounter, the Encounter holds its id, identifier, the subject reference, status unknown, and a class marked as unknown. R4 requires class, so instead of guessing one the endpoint returns it with only the standard data-absent-reason extension:

"class": {
  "extension": [
    { "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason", "valueCode": "unknown" }
  ]
}

Patient fields

Field	Type	What it holds	From the request	From the note
`id`	string	The resource ID inside the Bundle. Every `subject` and `patient` reference points to it.		Never. Always generated from the note text.
`identifier`	list of Identifier	One Identifier: `system` is `http://corti.app/fhir/identifier/patient`, `value` is the ID	`patient.identifier`	Never. Without your ID, the endpoint uses the generated `id`.
`gender`	code	`male`, `female`, `other`, or `unknown`. See the R4 value set.	`patient.gender`	”female”, “M”
`birthDate`	date	`YYYY`, `YYYY-MM`, or `YYYY-MM-DD`	`patient.birthDate`	”DOB: 1968-04-02”
`name`	list of HumanName	One HumanName with only `text`: the name as written, not split into family and given names. Left out when neither you nor the note states it.	`patient.name`	”Patient: Anna Miller”
`extension`	list of Extension	Mentions for `gender` and `birthDate`

Encounter fields

Field	Type	What it holds	From the request	From the note
`id`	string	The resource ID inside the Bundle. Every Condition, Procedure, and Observation `encounter` reference points to it.		Never. Always generated from the note text.
`identifier`	list of Identifier	One Identifier: `system` is `http://corti.app/fhir/identifier/encounter`, `value` is the ID. The `encounter` references repeat it.	`encounter.identifier`	Never. Without your ID, the endpoint uses the generated `id`.
`subject`	Reference	The Patient of the Bundle		Always set
`status`	code	`planned`, `arrived`, `triaged`, `in-progress`, `onleave`, `finished`, `cancelled`, `entered-in-error`, or `unknown`. Defaults to `in-progress` when the note describes the encounter without a status word, and to `unknown` when the note says nothing about the encounter. See the R4 value set.	`encounter.status`	”discharged” → `finished`
`class`	Coding	`AMB` ambulatory, `EMER` emergency, `IMP` inpatient encounter, `HH` home health, or `VR` virtual, from the HL7 ActCode system. See the R4 value set. When neither you nor the note states it, `class` carries only the data-absent-reason extension.	`encounter.class`	”seen in the ED” → `EMER`
`priority`	CodeableConcept	`R` Routine, `UR` Urgent, `EM` Emergency, `A` ASAP, `EL` Elective, or `S` Stat, from the HL7 ActPriority system. See the R4 value set.	`encounter.priority`	”elective admission” → `EL`
`type`	CodeableConcept list	The kind of visit, as text	`encounter.type`	”follow-up”
`serviceType`	CodeableConcept	The specialty, as text	`encounter.serviceType`	”cardiology”
`reasonCode`	CodeableConcept list	The reason for the visit, as text	`encounter.reasonCode`	”presents with chest pain”
`period`	Period	`start` and `end` as dateTime values: a date, or a date and time with seconds and a timezone offset. A request value with a time but no offset is rejected with a 422.	`encounter.period`	”Admitted 2026-04-03”
`extension`	list of Extension	Mentions for `status`, `class`, `priority`, `reason`, and `period`

The generated IDs are stable: the same note always gets the same Patient and Encounter id. Two different notes about the same patient get two different IDs, though. Only your own identifier ties notes from one patient together. Sending an identifier never changes the id.

Codes the endpoint can assign

Patient and Encounter use no clinical code systems. Every coded field holds a value from a fixed HL7 or FHIR list: gender from administrative gender, class from ActCode, and priority from ActPriority. type, serviceType, and reasonCode hold text only, so you can send any wording your system uses.

Example

This request sends every patient and encounter value:

{
  "context": { "context_type": "other", "data": "Discharge summary. 58-year-old woman admitted 03/04/2026 with community-acquired pneumonia." },
  "patient": {
    "identifier": "<your-patient-id>",
    "name": "Anna Miller",
    "gender": "female",
    "birthDate": "1968-04-02"
  },
  "encounter": {
    "identifier": "<your-encounter-id>",
    "status": "finished",
    "class": "inpatient",
    "priority": "urgent",
    "type": "Emergency admission",
    "serviceType": "Internal medicine",
    "reasonCode": "Community-acquired pneumonia",
    "period": { "start": "2026-04-03T14:20:00+02:00", "end": "2026-04-08T10:00:00+02:00" }
  }
}

It returns this Patient and Encounter. Every field comes from the request, so neither resource carries a mention.

Simplified
JSON

Resource	Field	Value
Patient	`identifier`	your patient ID
Patient	`gender`	`female`
Patient	`birthDate`	`1968-04-02`
Patient	`name`	Anna Miller
Encounter	`identifier`	your encounter ID
Encounter	`status`	`finished`
Encounter	`class`	`IMP` inpatient encounter
Encounter	`type`	Emergency admission
Encounter	`serviceType`	Internal medicine
Encounter	`priority`	`UR` Urgent
Encounter	`reasonCode`	Community-acquired pneumonia
Encounter	`period`	2026-04-03 14:20 to 2026-04-08 10:00

[
  {
    "fullUrl": "urn:uuid:b49ecda5-92db-5325-a7a9-f82c71500bad",
    "request": { "method": "POST", "url": "Patient", "ifNoneExist": "identifier=http://corti.app/fhir/identifier/patient|<your-patient-id>" },
    "resource": {
      "resourceType": "Patient",
      "id": "b49ecda5-92db-5325-a7a9-f82c71500bad",
      "identifier": [
        {
          "system": "http://corti.app/fhir/identifier/patient",
          "value": "<your-patient-id>"
        }
      ],
      "gender": "female",
      "birthDate": "1968-04-02",
      "name": [{ "text": "Anna Miller" }]
    }
  },
  {
    "fullUrl": "urn:uuid:29543af8-9ec2-528e-8a3b-1e891822d99d",
    "request": { "method": "POST", "url": "Encounter", "ifNoneExist": "identifier=http://corti.app/fhir/identifier/encounter|<your-encounter-id>" },
    "resource": {
      "resourceType": "Encounter",
      "id": "29543af8-9ec2-528e-8a3b-1e891822d99d",
      "identifier": [
        {
          "system": "http://corti.app/fhir/identifier/encounter",
          "value": "<your-encounter-id>"
        }
      ],
      "status": "finished",
      "class": {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
        "code": "IMP",
        "display": "inpatient encounter"
      },
      "type": [{ "text": "Emergency admission" }],
      "serviceType": { "text": "Internal medicine" },
      "priority": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v3-ActPriority",
            "code": "UR",
            "display": "Urgent"
          }
        ],
        "text": "Urgent"
      },
      "reasonCode": [{ "text": "Community-acquired pneumonia" }],
      "period": {
        "start": "2026-04-03T14:20:00+02:00",
        "end": "2026-04-08T10:00:00+02:00"
      },
      "subject": {
        "reference": "urn:uuid:b49ecda5-92db-5325-a7a9-f82c71500bad",
        "type": "Patient"
      }
    }
  }
]

The diagnosis “community-acquired pneumonia” also becomes a Condition with a SNOMED CT code, which references this Encounter. The Encounter’s reasonCode only holds the text you sent.

Clinical Text Generation

Medical Coding

FHIR Extraction

Clinical Assistant

What the endpoint reads from the note

Patient fields

Encounter fields

Codes the endpoint can assign

Example

Next steps

Reduce extraction errors

Condition resource group

​What the endpoint reads from the note

​Patient fields

​Encounter fields

​Codes the endpoint can assign

​Example

​Next steps

Reduce extraction errors

Condition resource group

What the endpoint reads from the note

Patient fields

Encounter fields

Codes the endpoint can assign

Example

Next steps