> ## 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.

# FHIR Extraction request and response

> Look up every request field, the response shape, and the errors and limits of the FHIR Extraction endpoint

This page lists every field of a FHIR Extraction request and response, and every error the endpoint returns. For a walkthrough, see the [quickstart](https://docs.corti.ai/fhir/quickstart.md).

```
POST https://api.$environment.corti.app/v2/tools/fhir/
```

> [!NOTE]
>
> FHIR Extraction is in **beta**. The request and response schemas can still change. [Contact us](mailto:help@corti.ai) to share feedback or report issues.

## Request body

| Parameter | Type | Definition |
| - | - | - |
| `context` | object | **Required.** The note, in one of two forms. `{ "context_type": "other", "data": "..." }` sends the note as one string. `{ "context_type": "clinical_note", "data": [{ "id": "...", "title": "...", "body": "..." }] }` sends it as titled sections, and the endpoint writes each one into the note as `Title:` on its own line, then the body, then a blank line. Every section needs an `id`, a `title`, and a `body`. |
| `patient` | object | Patient values you already know. See [`patient`](#patient). |
| `encounter` | object | Encounter values you already know. See [`encounter`](#encounter). |
| `resourceGroups` | array | The resource groups, and categories within them, to produce. Omit it to produce everything. See [Filter reference](https://docs.corti.ai/fhir/filter-reference.md#resourcegroups). |
| `filters` | array | Restrictions on which codes the endpoint may assign. Omit it to allow every code in the built-in scope. See [Filter reference](https://docs.corti.ai/fhir/filter-reference.md#filters). |

### `patient`

Each value you send replaces the value the endpoint would read from the note. [Reduce extraction errors](https://docs.corti.ai/fhir/reduce-errors.md#send-what-you-already-know) explains why you should send every field you have.

| Parameter | Type | Definition |
| - | - | - |
| `identifier` | string | Your ID for the patient. The response uses it as `Patient.identifier[0].value`. Without it, the endpoint generates an ID. |
| `name` | string | The patient's name. |
| `gender` | string | One of `male`, `female`, `other`, or `unknown`, from the R4 [administrative gender](https://hl7.org/fhir/R4/valueset-administrative-gender.html) value set. |
| `birthDate` | string | Date of birth as `YYYY`, `YYYY-MM`, or `YYYY-MM-DD`. A time of day or free text such as `"15/03/1968"` returns a 422. |

### `encounter`

Each value you send replaces the value the endpoint would read from the note.

| Parameter | Type | Definition |
| - | - | - |
| `identifier` | string | Your ID for the encounter. The response uses it as `Encounter.identifier[0].value`, and every Condition, Procedure, and Observation `encounter` reference repeats it. Without it, the endpoint generates an ID. |
| `status` | string | One of `planned`, `arrived`, `triaged`, `in-progress`, `onleave`, `finished`, `cancelled`, `entered-in-error`, or `unknown`, from the R4 [encounter status](https://hl7.org/fhir/R4/valueset-encounter-status.html) value set. |
| `class` | string | One of `ambulatory`, `emergency`, `inpatient`, `home-health`, or `virtual`. The response maps them to the R4 [ActEncounterCode](https://hl7.org/fhir/R4/v3/ActEncounterCode/vs.html) codes `AMB`, `EMER`, `IMP`, `HH`, and `VR`. |
| `priority` | string | One of `routine`, `urgent`, `emergency`, `asap`, `elective`, or `stat`. The response maps them to the R4 [ActPriority](https://hl7.org/fhir/R4/v3/ActPriority/vs.html) codes `R`, `UR`, `EM`, `A`, `EL`, and `S`. |
| `type` | string | Free text, for example `"Diabetes follow-up"`. |
| `serviceType` | string | Free text, for example `"Endocrinology"`. |
| `reasonCode` | string | Free text, for example `"Poor glycemic control"`. |
| `period` | object | `start` and `end` as R4 [dateTime](https://docs.corti.ai/fhir/datatypes.md#primitive-types) values: a date, such as `"2026-11-03"`, or a date and time with seconds and a timezone offset, such as `"2026-11-03T09:00:00+01:00"`. A time without seconds or an offset, such as `"2026-11-03T09:00"`, returns a 422. |

## Response body

| Field | Type | Definition |
| - | - | - |
| `bundle` | object | A [FHIR R4 Bundle](https://hl7.org/fhir/R4/bundle.html) with all extracted resources. |
| `usageInfo` | object | Credits consumed for this request, as `creditsConsumed`. |

The Bundle has these fields:

| Field | Type | Definition |
| - | - | - |
| `resourceType` | string | Always `Bundle`. |
| `type` | string | Always `transaction`. POST the Bundle as it is to your FHIR server to store the resources. |
| `timestamp` | string | When the endpoint created the Bundle, as an ISO 8601 date-time with timezone. |
| `entry` | array | One `{ "fullUrl": "urn:uuid:...", "resource": { ... }, "request": { ... } }` per resource. The `fullUrl` matches the resource's `id`, and every `subject`, `patient`, and `encounter` reference names a `fullUrl` in the same Bundle. `request` is `{ "method": "POST", "url": "<resourceType>" }`; on the Patient and the Encounter it also has `ifNoneExist` with their identifier, so a server that already holds them links to the existing resource. |

The entries always come in the same order: one Patient, one Encounter, then Conditions, AllergyIntolerances, FamilyMemberHistories, Procedures, and Observations. The [resource group pages](https://docs.corti.ai/fhir/resource-groups/condition.md) describe every resource and field.

## Errors

Every error uses the same envelope:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request context is empty. Provide a non-empty note or at least one non-empty section.",
    "request_id": "<request-id>"
  }
}
```

| Status | `code` | When |
| - | - | - |
| 400 | `VALIDATION_ERROR` | The `context` string is blank or every section `body` is blank, an enum value is invalid (for example `encounter.class: "outpatient"`), `context_type` is not `other` or `clinical_note`, `data` does not match its `context_type` (for example a section without a `body`), or a `resourceGroups` or `filters` entry is invalid. For an invalid enum or `context`, `message` is `Invalid request input.` and `details` lists each field. For the other cases, `message` names the value. [Filter reference](https://docs.corti.ai/fhir/filter-reference.md#validation-rules) lists every filter rule. |
| 408 | `TIMEOUT_ERROR` | The request took too long. Retry, or split a very long note. |
| 413 | `CONTEXT_TOO_LARGE` | The note is longer than the limit below. |
| 422 | `VALIDATION_ERROR` | The body does not match the schema, for example a `context` without `context_type`, an empty `resourceGroups` or `categories` list, a filter condition whose `value` does not fit its `op`, a `birthDate` with a time of day, or an `encounter.period` time without seconds and a timezone offset. `details` lists each field. |
| 500 | `INTERNAL_ERROR` | The service failed. Retry, and share `request_id` with support if it keeps failing. |

## Limits

| Limit | Value |
| - | - |
| Length of the note, with section titles | 256,000 characters |
| Alternatives per field | 10 |
| Nesting depth of filter condition groups | 3 levels |

## Next steps

> [card] [FHIR filter reference](https://docs.corti.ai/fhir/filter-reference.md)
>
> Look up the fields and rules of `resourceGroups` and `filters`.

> [card] [Condition resource group](https://docs.corti.ai/fhir/resource-groups/condition.md)
>
> See every field the endpoint fills on a Condition.


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