> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corti.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Patient & Encounter resource groups

> Learn what the Patient and Encounter resources in every FHIR Extraction response contain, and why you should pass the values you already know

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](https://hl7.org/fhir/R4/patient.html) and [FHIR R4 Encounter](https://hl7.org/fhir/R4/encounter.html) 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](https://docs.corti.ai/fhir/reduce-errors.md#send-what-you-already-know) 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](https://hl7.org/fhir/R4/extension-data-absent-reason.html) extension:

```json theme={null}
"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`](https://hl7.org/fhir/R4/resource-definitions.html#Resource.id) | [string](https://docs.corti.ai/fhir/datatypes.md#primitive-types) | The resource ID inside the Bundle. Every `subject` and `patient` reference points to it. | | Never. Always generated from the note text. |
| [`identifier`](https://hl7.org/fhir/R4/patient-definitions.html#Patient.identifier) | list of [Identifier](https://docs.corti.ai/fhir/datatypes.md#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`](https://hl7.org/fhir/R4/patient-definitions.html#Patient.gender) | [code](https://docs.corti.ai/fhir/datatypes.md#primitive-types) | `male`, `female`, `other`, or `unknown`. See the [R4 value set](https://hl7.org/fhir/R4/valueset-administrative-gender.html). | `patient.gender` | "female", "M" |
| [`birthDate`](https://hl7.org/fhir/R4/patient-definitions.html#Patient.birthDate) | [date](https://docs.corti.ai/fhir/datatypes.md#primitive-types) | `YYYY`, `YYYY-MM`, or `YYYY-MM-DD` | `patient.birthDate` | "DOB: 1968-04-02" |
| [`name`](https://hl7.org/fhir/R4/patient-definitions.html#Patient.name) | list of [HumanName](https://hl7.org/fhir/R4/datatypes.html#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`](https://hl7.org/fhir/R4/extensibility.html#Extension) | list of [Extension](https://docs.corti.ai/fhir/datatypes.md#extension) | Mentions for `gender` and `birthDate` | | |

## Encounter fields

| Field | Type | What it holds | From the request | From the note |
| - | - | - | - | - |
| [`id`](https://hl7.org/fhir/R4/resource-definitions.html#Resource.id) | [string](https://docs.corti.ai/fhir/datatypes.md#primitive-types) | The resource ID inside the Bundle. Every Condition, Procedure, and Observation `encounter` reference points to it. | | Never. Always generated from the note text. |
| [`identifier`](https://hl7.org/fhir/R4/encounter-definitions.html#Encounter.identifier) | list of [Identifier](https://docs.corti.ai/fhir/datatypes.md#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`](https://hl7.org/fhir/R4/encounter-definitions.html#Encounter.subject) | [Reference](https://docs.corti.ai/fhir/datatypes.md#reference) | The Patient of the Bundle | | Always set |
| [`status`](https://hl7.org/fhir/R4/encounter-definitions.html#Encounter.status) | [code](https://docs.corti.ai/fhir/datatypes.md#primitive-types) | `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](https://hl7.org/fhir/R4/valueset-encounter-status.html). | `encounter.status` | "discharged" → `finished` |
| [`class`](https://hl7.org/fhir/R4/encounter-definitions.html#Encounter.class) | [Coding](https://docs.corti.ai/fhir/datatypes.md#coding) | `AMB` ambulatory, `EMER` emergency, `IMP` inpatient encounter, `HH` home health, or `VR` virtual, from the HL7 ActCode system. See the [R4 value set](https://hl7.org/fhir/R4/v3/ActEncounterCode/vs.html). When neither you nor the note states it, `class` carries only the data-absent-reason extension. | `encounter.class` | "seen in the ED" → `EMER` |
| [`priority`](https://hl7.org/fhir/R4/encounter-definitions.html#Encounter.priority) | [CodeableConcept](https://docs.corti.ai/fhir/datatypes.md#codeableconcept) | `R` Routine, `UR` Urgent, `EM` Emergency, `A` ASAP, `EL` Elective, or `S` Stat, from the HL7 ActPriority system. See the [R4 value set](https://hl7.org/fhir/R4/v3/ActPriority/vs.html). | `encounter.priority` | "elective admission" → `EL` |
| [`type`](https://hl7.org/fhir/R4/encounter-definitions.html#Encounter.type) | [CodeableConcept](https://docs.corti.ai/fhir/datatypes.md#codeableconcept) list | The kind of visit, as text | `encounter.type` | "follow-up" |
| [`serviceType`](https://hl7.org/fhir/R4/encounter-definitions.html#Encounter.serviceType) | [CodeableConcept](https://docs.corti.ai/fhir/datatypes.md#codeableconcept) | The specialty, as text | `encounter.serviceType` | "cardiology" |
| [`reasonCode`](https://hl7.org/fhir/R4/encounter-definitions.html#Encounter.reasonCode) | [CodeableConcept](https://docs.corti.ai/fhir/datatypes.md#codeableconcept) list | The reason for the visit, as text | `encounter.reasonCode` | "presents with chest pain" |
| [`period`](https://hl7.org/fhir/R4/encounter-definitions.html#Encounter.period) | [Period](https://docs.corti.ai/fhir/datatypes.md#period) | `start` and `end` as [dateTime](https://docs.corti.ai/fhir/datatypes.md#primitive-types) 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`](https://hl7.org/fhir/R4/extensibility.html#Extension) | list of [Extension](https://docs.corti.ai/fhir/datatypes.md#extension) | Mentions for `status`, `class`, `priority`, `reason`, and `period` | | |

> [!NOTE]
>
> 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:

```json theme={null}
{
  "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.

> [tab] Simplified
>
> | 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 |

> [tab] JSON
>
> ```json theme={null}
> [
>   {
>     "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](https://docs.corti.ai/fhir/resource-groups/condition.md) with a SNOMED CT code, which references this Encounter. The Encounter's `reasonCode` only holds the text you sent.

## Next steps

> [card] [Reduce extraction errors](https://docs.corti.ai/fhir/reduce-errors.md)
>
> Learn where each patient and encounter value comes from in an EHR.

> [card] [Condition resource group](https://docs.corti.ai/fhir/resource-groups/condition.md)
>
> Learn how diagnoses, problems, symptoms, and signs look in FHIR.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.