FHIR Extraction quickstart

This quickstart sends one short note to the FHIR Extraction endpoint and walks through the response. At the end, you have a FHIR Bundle with a Patient, an Encounter, and one resource per clinical fact in the note.

FHIR Extraction is in beta. The request and response schemas can still change. Contact us to share feedback or report issues.

Prerequisites

An API client. You need your tenant name, environment (eu or us), and an access token. See Creating API clients and the authentication quickstart.
Basic FHIR knowledge. If terms such as CodeableConcept or Bundle are new to you, read FHIR basics first.

Send a note

The example note has three facts in it: a diagnosis, a blood pressure reading, and an allergy.

58-year-old woman with type 2 diabetes, poorly controlled. BP 150/90. Penicillin causes hives.

The request sends the note in context, the only required field. It also sends the patient and encounter values that your system already knows: your own IDs, so the response links to your records, and the demographics and visit details, so the endpoint does not have to read them from the note. Do the same in your own requests. Reduce extraction errors explains why.

import requests

# Replace these with your values
ENCOUNTER_IDENTIFIER = "<id-of-your-choosing>"
ENVIRONMENT = "<eu-or-us>"
PATIENT_IDENTIFIER = "<id-of-your-choosing>"
TENANT = "<your-tenant-name>"
TOKEN = "<your-access-token>"

response = requests.post(
    f"https://api.{ENVIRONMENT}.corti.app/v2/tools/fhir/",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Tenant-Name": TENANT,
        "Content-Type": "application/json",
    },
    json={
        "context": {
            "context_type": "other",
            "data": "58-year-old woman with type 2 diabetes, poorly controlled. BP 150/90. Penicillin causes hives.",
        },
        "patient": {
            "identifier": PATIENT_IDENTIFIER,
            "name": "Anna Miller",
            "gender": "female",
            "birthDate": "1968-04-02",
        },
        "encounter": {
            "identifier": ENCOUNTER_IDENTIFIER,
            "status": "finished",
            "class": "ambulatory",
            "priority": "routine",
            "type": "Diabetes follow-up",
            "serviceType": "Endocrinology",
            "reasonCode": "Poor glycemic control",
            "period": {"start": "2026-11-03T09:00:00+01:00", "end": "2026-11-03T09:30:00+01:00"},
        },
    },
)
response.raise_for_status()

for entry in response.json()["bundle"]["entry"]:
    resource = entry["resource"]
    print(resource["resourceType"], resource.get("code", {}).get("text"))

# Replace these with your values
ENCOUNTER_IDENTIFIER="<id-of-your-choosing>"
ENVIRONMENT="<eu-or-us>"
PATIENT_IDENTIFIER="<id-of-your-choosing>"
TENANT="<your-tenant-name>"
TOKEN="<your-access-token>"

curl -X POST "https://api.${ENVIRONMENT}.corti.app/v2/tools/fhir/" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}" \
  -H "Content-Type: application/json" \
  -d '{
    "context": { "context_type": "other", "data": "58-year-old woman with type 2 diabetes, poorly controlled. BP 150/90. Penicillin causes hives." },
    "patient": {
      "identifier": "'"${PATIENT_IDENTIFIER}"'",
      "name": "Anna Miller",
      "gender": "female",
      "birthDate": "1968-04-02"
    },
    "encounter": {
      "identifier": "'"${ENCOUNTER_IDENTIFIER}"'",
      "status": "finished",
      "class": "ambulatory",
      "priority": "routine",
      "type": "Diabetes follow-up",
      "serviceType": "Endocrinology",
      "reasonCode": "Poor glycemic control",
      "period": { "start": "2026-11-03T09:00:00+01:00", "end": "2026-11-03T09:30:00+01:00" }
    }
  }'

Request and response lists every request field and its allowed values.

Read the response

The response has two top-level fields: bundle, a FHIR Bundle with all resources, and usageInfo, the credits consumed by the request. For the example note, the Bundle holds six resources:

#	Resource	What it says	Source
1	`Patient`	Your patient ID, name, gender `female`, and date of birth	the request
2	`Encounter`	Your encounter ID, status `finished`, class `AMB` (ambulatory), priority `R` (routine), type, specialty, reason, and visit times	the request
3	`Condition`	`44054006` Type 2 diabetes mellitus, `active`	”type 2 diabetes”
4	`AllergyIntolerance`	`91936005` Allergy to penicillin, category `medication`, reaction “hives"	"Penicillin causes hives”
5	`Observation`	`8480-6` Systolic blood pressure, 150 mmHg	”BP 150”
6	`Observation`	`8462-4` Diastolic blood pressure, 90 mmHg	”90”

Notice that the endpoint splits the blood pressure into two Observations, one for each number. Every measurement gets its own resource. The full response below shows the real JSON. It is long, mostly because of the extension entries, which the next section explains. It is valid FHIR R4: each clinical resource points to the Patient and Encounter through their fullUrl. See How the response meets FHIR R4.

Full response JSON

{
  "bundle": {
    "resourceType": "Bundle",
    "type": "transaction",
    "timestamp": "2026-11-03T09:14:22.512345+00:00",
    "entry": [
      {
        "fullUrl": "urn:uuid:b49ecda5-92db-5325-a7a9-f82c71500bad",
        "request": { "method": "POST", "url": "Patient", "ifNoneExist": "identifier=http://corti.app/fhir/identifier/patient|pat-10442" },
        "resource": {
          "resourceType": "Patient",
          "id": "b49ecda5-92db-5325-a7a9-f82c71500bad",
          "identifier": [
            {
              "system": "http://corti.app/fhir/identifier/patient",
              "value": "pat-10442"
            }
          ],
          "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|enc-88213" },
        "resource": {
          "resourceType": "Encounter",
          "id": "29543af8-9ec2-528e-8a3b-1e891822d99d",
          "identifier": [
            {
              "system": "http://corti.app/fhir/identifier/encounter",
              "value": "enc-88213"
            }
          ],
          "status": "finished",
          "class": {
            "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
            "code": "AMB",
            "display": "ambulatory"
          },
          "type": [{ "text": "Diabetes follow-up" }],
          "serviceType": { "text": "Endocrinology" },
          "priority": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v3-ActPriority",
                "code": "R",
                "display": "Routine"
              }
            ],
            "text": "Routine"
          },
          "reasonCode": [{ "text": "Poor glycemic control" }],
          "period": {
            "start": "2026-11-03T09:00:00+01:00",
            "end": "2026-11-03T09:30:00+01:00"
          },
          "subject": {
            "reference": "urn:uuid:b49ecda5-92db-5325-a7a9-f82c71500bad",
            "type": "Patient"
          }
        }
      },
      {
        "fullUrl": "urn:uuid:3b3921ad-2029-560e-b13c-0505d69698bd",
        "request": { "method": "POST", "url": "Condition" },
        "resource": {
          "extension": [
            {
              "url": "https://docs.corti.ai/fhir/StructureDefinition/mention",
              "extension": [
                { "url": "field", "valueString": "code" },
                {
                  "url": "evidence",
                  "extension": [
                    { "url": "start", "valueInteger": 23 },
                    { "url": "end", "valueInteger": 38 },
                    { "url": "text", "valueString": "type 2 diabetes" }
                  ]
                }
              ]
            },
            {
              "url": "https://docs.corti.ai/fhir/StructureDefinition/alternative",
              "extension": [
                { "url": "field", "valueString": "code" },
                {
                  "url": "alternative",
                  "valueCodeableConcept": {
                    "coding": [
                      {
                        "system": "http://snomed.info/sct",
                        "code": "443694000",
                        "display": "Uncontrolled type 2 diabetes mellitus"
                      }
                    ],
                    "text": "Uncontrolled type 2 diabetes mellitus"
                  }
                }
              ]
            }
          ],
          "resourceType": "Condition",
          "id": "3b3921ad-2029-560e-b13c-0505d69698bd",
          "clinicalStatus": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                "code": "active",
                "display": "Active"
              }
            ],
            "text": "Active"
          },
          "code": {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "44054006",
                "display": "Type 2 diabetes mellitus"
              }
            ],
            "text": "Type 2 diabetes mellitus"
          },
          "subject": {
            "reference": "urn:uuid:b49ecda5-92db-5325-a7a9-f82c71500bad",
            "type": "Patient"
          },
          "encounter": {
            "reference": "urn:uuid:29543af8-9ec2-528e-8a3b-1e891822d99d",
            "type": "Encounter",
            "identifier": {
              "system": "http://corti.app/fhir/identifier/encounter",
              "value": "enc-88213"
            }
          }
        }
      },
      {
        "fullUrl": "urn:uuid:e1153f83-e4c1-5aed-8237-5bbe5c0f4ed8",
        "request": { "method": "POST", "url": "AllergyIntolerance" },
        "resource": {
          "extension": [
            {
              "url": "https://docs.corti.ai/fhir/StructureDefinition/mention",
              "extension": [
                { "url": "field", "valueString": "code" },
                {
                  "url": "evidence",
                  "extension": [
                    { "url": "start", "valueInteger": 70 },
                    { "url": "end", "valueInteger": 80 },
                    { "url": "text", "valueString": "Penicillin" }
                  ]
                }
              ]
            }
          ],
          "resourceType": "AllergyIntolerance",
          "id": "e1153f83-e4c1-5aed-8237-5bbe5c0f4ed8",
          "clinicalStatus": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
                "code": "active",
                "display": "Active"
              }
            ],
            "text": "Active"
          },
          "type": "allergy",
          "category": ["medication"],
          "patient": {
            "reference": "urn:uuid:b49ecda5-92db-5325-a7a9-f82c71500bad",
            "type": "Patient"
          },
          "code": {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "91936005",
                "display": "Allergy to penicillin"
              }
            ],
            "text": "Allergy to penicillin"
          },
          "reaction": [{ "manifestation": [{ "text": "hives" }] }]
        }
      },
      {
        "fullUrl": "urn:uuid:48b0a0d5-4786-575e-82e1-ffd6076b9f4d",
        "request": { "method": "POST", "url": "Observation" },
        "resource": {
          "extension": [
            {
              "url": "https://docs.corti.ai/fhir/StructureDefinition/mention",
              "extension": [
                { "url": "field", "valueString": "code" },
                {
                  "url": "evidence",
                  "extension": [
                    { "url": "start", "valueInteger": 59 },
                    { "url": "end", "valueInteger": 61 },
                    { "url": "text", "valueString": "BP" }
                  ]
                }
              ]
            },
            {
              "url": "https://docs.corti.ai/fhir/StructureDefinition/mention",
              "extension": [
                { "url": "field", "valueString": "valueQuantity" },
                {
                  "url": "evidence",
                  "extension": [
                    { "url": "start", "valueInteger": 62 },
                    { "url": "end", "valueInteger": 65 },
                    { "url": "text", "valueString": "150" }
                  ]
                }
              ]
            }
          ],
          "resourceType": "Observation",
          "id": "48b0a0d5-4786-575e-82e1-ffd6076b9f4d",
          "status": "final",
          "category": [
            {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                  "code": "vital-signs",
                  "display": "Vital Signs"
                }
              ],
              "text": "Vital Signs"
            }
          ],
          "subject": {
            "reference": "urn:uuid:b49ecda5-92db-5325-a7a9-f82c71500bad",
            "type": "Patient"
          },
          "encounter": {
            "reference": "urn:uuid:29543af8-9ec2-528e-8a3b-1e891822d99d",
            "type": "Encounter",
            "identifier": {
              "system": "http://corti.app/fhir/identifier/encounter",
              "value": "enc-88213"
            }
          },
          "code": {
            "coding": [
              {
                "system": "http://loinc.org",
                "code": "8480-6",
                "display": "Systolic blood pressure"
              }
            ],
            "text": "Systolic blood pressure"
          },
          "valueQuantity": {
            "value": 150,
            "unit": "mmHg",
            "system": "http://unitsofmeasure.org"
          }
        }
      },
      {
        "fullUrl": "urn:uuid:545dd885-946d-5aad-8481-4468bf0ab359",
        "request": { "method": "POST", "url": "Observation" },
        "resource": {
          "extension": [
            {
              "url": "https://docs.corti.ai/fhir/StructureDefinition/mention",
              "extension": [
                { "url": "field", "valueString": "valueQuantity" },
                {
                  "url": "evidence",
                  "extension": [
                    { "url": "start", "valueInteger": 66 },
                    { "url": "end", "valueInteger": 68 },
                    { "url": "text", "valueString": "90" }
                  ]
                }
              ]
            }
          ],
          "resourceType": "Observation",
          "id": "545dd885-946d-5aad-8481-4468bf0ab359",
          "status": "final",
          "category": [
            {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                  "code": "vital-signs",
                  "display": "Vital Signs"
                }
              ],
              "text": "Vital Signs"
            }
          ],
          "subject": {
            "reference": "urn:uuid:b49ecda5-92db-5325-a7a9-f82c71500bad",
            "type": "Patient"
          },
          "encounter": {
            "reference": "urn:uuid:29543af8-9ec2-528e-8a3b-1e891822d99d",
            "type": "Encounter",
            "identifier": {
              "system": "http://corti.app/fhir/identifier/encounter",
              "value": "enc-88213"
            }
          },
          "code": {
            "coding": [
              {
                "system": "http://loinc.org",
                "code": "8462-4",
                "display": "Diastolic blood pressure"
              }
            ],
            "text": "Diastolic blood pressure"
          },
          "valueQuantity": {
            "value": 90,
            "unit": "mmHg",
            "system": "http://unitsofmeasure.org"
          }
        }
      }
    ]
  },
  "usageInfo": { "creditsConsumed": 42 }
}

A coding entry can also carry a version field with the version of the code system the endpoint used. The examples in these docs leave it out.

Check each value against the note

Each clinical resource carries extension entries that point back to the note:

Mentions link a field to the words that support it. The systolic Observation has a mention for code (“BP”, characters 59 to 61) and one for valueQuantity (“150”, characters 62 to 65).
Alternatives list other codes that could fit. The Condition offers 443694000 Uncontrolled type 2 diabetes mellitus as an alternative to 44054006 Type 2 diabetes mellitus.

The Patient and Encounter carry no mentions, because every value in them comes from the request. Every value points back to the note explains how to read both extensions.

Next steps

How FHIR Extraction works

Learn the rules behind every response, such as positive codes and status fields.

Reduce extraction errors

Send what you know, skip structured data, and review the results.

Filter FHIR resources

Produce only the resources you need and restrict the codes they carry.

FHIR Extraction request and response

Look up every request field, error, and limit.

Clinical Text Generation

Medical Coding

FHIR Extraction

Clinical Assistant

Prerequisites

Send a note

Read the response

Check each value against the note

Next steps

How FHIR Extraction works

Reduce extraction errors

Filter FHIR resources

FHIR Extraction request and response

​Prerequisites

​Send a note

​Read the response

​Check each value against the note

​Next steps

How FHIR Extraction works

Reduce extraction errors

Filter FHIR resources

FHIR Extraction request and response

Prerequisites

Send a note

Read the response

Check each value against the note

Next steps