FHIR Extraction request and response

This page lists every field of a FHIR Extraction request and response, and every error the endpoint returns. For a walkthrough, see the quickstart.

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

FHIR Extraction is in beta. The request and response schemas can still change. Contact us 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`.
`encounter`	object	Encounter values you already know. See `encounter`.
`resourceGroups`	array	The resource groups, and categories within them, to produce. Omit it to produce everything. See Filter reference.
`filters`	array	Restrictions on which codes the endpoint may assign. Omit it to allow every code in the built-in scope. See Filter reference.

`patient`

Each value you send replaces the value the endpoint would read from the note. Reduce extraction errors 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 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 value set.
`class`	string	One of `ambulatory`, `emergency`, `inpatient`, `home-health`, or `virtual`. The response maps them to the R4 ActEncounterCode 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 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 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 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 describe every resource and field.

Errors

Every error uses the same envelope:

{
  "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 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

FHIR filter reference

Look up the fields and rules of resourceGroups and filters.

Condition resource group

See every field the endpoint fills on a Condition.

Clinical Text Generation

Medical Coding

FHIR Extraction

Clinical Assistant

Request body

`patient`

`encounter`

Response body

Errors

Limits

Next steps

FHIR filter reference

Condition resource group

​Request body

​patient

​encounter

​Response body

​Errors

​Limits

​Next steps

FHIR filter reference

Condition resource group

Request body

`patient`

`encounter`

Response body

Errors

Limits

Next steps