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

# Procedure resource group

> Learn how surgery, therapy, counseling, and other interventions become FHIR R4 Procedure resources, and which fields the Corti API fills

A Procedure resource records one action performed on or for the patient. That covers surgery, but also counseling, education, physiotherapy, and diagnostic procedures. The endpoint codes each procedure with [SNOMED CT](https://www.snomed.org/). The resource follows the [FHIR R4 Procedure](https://hl7.org/fhir/R4/procedure.html) specification, and each field name below links to its R4 definition.

## What becomes a Procedure

| Note says | Procedure `code` | `category` |
| - | - | - |
| "Laparoscopic appendectomy in March 2025" | `6025007` Laparoscopic appendectomy | Surgical procedure |
| "Counseled on smoking cessation" | `225323000` Smoking cessation education | Education |
| "Chest X-ray taken" | `399208008` Plain chest X-ray | Imaging |
| "Planned colonoscopy, not done because of poor bowel prep" | `73761001` Colonoscopy, with `status: not-done` | |

The *results* of a procedure go into an [Observation](https://docs.corti.ai/fhir/resource-groups/observation.md). "Chest X-ray shows right lower lobe consolidation" gives one Procedure for the X-ray, and one imaging Observation for the consolidation.

## Procedures not done

The `code` names the procedure in positive form. A procedure that did not happen keeps its own code and gets a `status` instead:

| Note says | `code` | `status` |
| - | - | - |
| "Colonoscopy performed" | `73761001` Colonoscopy | `completed` |
| "Colonoscopy not done because of poor bowel prep" | `73761001` Colonoscopy | `not-done` |
| "Colonoscopy scheduled for next week" | `73761001` Colonoscopy | `preparation` |

Check `status` before you treat a Procedure as performed.

## Fields

| Field | Type | What it holds | Example from a note |
| - | - | - | - |
| [`code`](https://hl7.org/fhir/R4/procedure-definitions.html#Procedure.code) | [CodeableConcept](https://docs.corti.ai/fhir/datatypes.md#codeableconcept) | The procedure, in SNOMED CT | "appendectomy" → `80146002` Appendectomy |
| [`status`](https://hl7.org/fhir/R4/procedure-definitions.html#Procedure.status) | [code](https://docs.corti.ai/fhir/datatypes.md#primitive-types) | `completed` by default. Also `preparation`, `in-progress`, `not-done`, `on-hold`, `stopped`, `entered-in-error`, or `unknown`. See the [R4 value set](https://hl7.org/fhir/R4/valueset-event-status.html). | "scheduled for next week" → `preparation` |
| [`category`](https://hl7.org/fhir/R4/procedure-definitions.html#Procedure.category) | [CodeableConcept](https://docs.corti.ai/fhir/datatypes.md#codeableconcept) | One of nine SNOMED CT categories: Psychiatry procedure or service, Counselling, Education, Surgical procedure, Laboratory procedure, Imaging, Measurement procedure, Chiropractic manipulation, or Social service procedure. See the [R4 value set](https://hl7.org/fhir/R4/valueset-procedure-category.html). | |
| [`bodySite`](https://hl7.org/fhir/R4/procedure-definitions.html#Procedure.bodySite) | [CodeableConcept](https://docs.corti.ai/fhir/datatypes.md#codeableconcept) list | The body structure, in SNOMED CT | "right hip replacement" → right hip joint structure |
| [`performedDateTime`](https://hl7.org/fhir/R4/procedure-definitions.html#Procedure.performed_x_) or [`performedString`](https://hl7.org/fhir/R4/procedure-definitions.html#Procedure.performed_x_) | [dateTime](https://docs.corti.ai/fhir/datatypes.md#primitive-types) or [string](https://docs.corti.ai/fhir/datatypes.md#primitive-types) | When it was done. A date only when the note states one. | "on 2025-03-14" → `performedDateTime: "2025-03-14"`. "in March 2025" → `performedString: "March 2025"` |
| [`reasonCode`](https://hl7.org/fhir/R4/procedure-definitions.html#Procedure.reasonCode) | [CodeableConcept](https://docs.corti.ai/fhir/datatypes.md#codeableconcept) list | Why, as text | "for suspected appendicitis" |
| [`outcome`](https://hl7.org/fhir/R4/procedure-definitions.html#Procedure.outcome) | [CodeableConcept](https://docs.corti.ai/fhir/datatypes.md#codeableconcept) | The result, as text | "uncomplicated" |
| [`complication`](https://hl7.org/fhir/R4/procedure-definitions.html#Procedure.complication) | [CodeableConcept](https://docs.corti.ai/fhir/datatypes.md#codeableconcept) list | Complications, as text | "post-operative wound infection" |
| [`performer`](https://hl7.org/fhir/R4/procedure-definitions.html#Procedure.performer) | list of `{ function, actor }` | Who did it, as text. R4 requires `actor`: when the note names a role but no person, `actor` is marked unknown with the [data-absent-reason](https://hl7.org/fhir/R4/extension-data-absent-reason.html) extension. | "by Dr. Lee" → `actor.display: "Dr. Lee"` |
| [`partOf`](https://hl7.org/fhir/R4/procedure-definitions.html#Procedure.partOf) | [Reference](https://docs.corti.ai/fhir/datatypes.md#reference) list | A larger procedure this one belongs to, as `display` text | |
| [`note`](https://hl7.org/fhir/R4/procedure-definitions.html#Procedure.note) | list of [Annotation](https://docs.corti.ai/fhir/datatypes.md#annotation) | Extra context | |
| [`subject`](https://hl7.org/fhir/R4/procedure-definitions.html#Procedure.subject) | [Reference](https://docs.corti.ai/fhir/datatypes.md#reference) | The Patient of the Bundle | |
| [`encounter`](https://hl7.org/fhir/R4/procedure-definitions.html#Procedure.encounter) | [Reference](https://docs.corti.ai/fhir/datatypes.md#reference) | The Encounter of the note | |
| [`extension`](https://hl7.org/fhir/R4/extensibility.html#Extension) | list of [Extension](https://docs.corti.ai/fhir/datatypes.md#extension) | [Mentions and alternatives](https://docs.corti.ai/fhir/how-it-works.md#every-value-points-back-to-the-note) | |

## Codes the endpoint can assign

The endpoint only searches a fixed part of each coding system for each field. A code outside that part never appears, and a [filter](https://docs.corti.ai/fhir/filter-reference.md#how-filters-combine) can only narrow the part further, never widen it. [Codes come from a fixed scope](https://docs.corti.ai/fhir/how-it-works.md#codes-come-from-a-fixed-scope) explains why.

| Field | Coding system | Allowed codes | Example |
| - | - | - | - |
| `code` | SNOMED CT | Semantic tag `procedure` | `80146002` Appendectomy |
| `bodySite` | SNOMED CT | `442083009` Anatomical or acquired body structure, and its descendants | `66754008` Appendix structure |
| `category` | SNOMED CT | A fixed list of nine: `24642003` Psychiatry procedure or service, `409063005` Counselling, `409073007` Education, `387713003` Surgical procedure, `108252007` Laboratory procedure, `363679005` Imaging, `122869004` Measurement procedure, `46947000` Chiropractic manipulation, `410606002` Social service procedure | |

Codes with the semantic tag `regime/therapy`, such as many medication regimens, are outside the allowed set. `reasonCode`, `outcome`, and `complication` hold text, so the endpoint assigns no codes there.

## Example

```text theme={null}
Laparoscopic appendectomy in March 2025 for acute appendicitis. Uncomplicated recovery.
```

> [tab] Simplified
>
> | Field | Value |
> | - | - |
> | `code` | `6025007` Laparoscopic appendectomy |
> | `status` | `completed` |
> | `category` | `387713003` Surgical procedure |
> | `performedString` | `March 2025` |
> | `reasonCode` | "acute appendicitis" |
> | `outcome` | "Uncomplicated recovery" |

> [tab] JSON
>
> ```json theme={null}
> {
>   "resourceType": "Procedure",
>   "id": "a2e6c4f1-9b37-5d08-8c5e-4f1b7a3d9e26",
>   "status": "completed",
>   "category": {
>     "coding": [
>       {
>         "system": "http://snomed.info/sct",
>         "code": "387713003",
>         "display": "Surgical procedure"
>       }
>     ],
>     "text": "Surgical procedure"
>   },
>   "code": {
>     "coding": [
>       {
>         "system": "http://snomed.info/sct",
>         "code": "6025007",
>         "display": "Laparoscopic appendectomy"
>       }
>     ],
>     "text": "Laparoscopic appendectomy"
>   },
>   "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"
>     }
>   },
>   "performedString": "March 2025",
>   "reasonCode": [{ "text": "acute appendicitis" }],
>   "outcome": { "text": "Uncomplicated recovery" }
> }
> ```

The same note also produces a Condition for "acute appendicitis". The Procedure's `reasonCode` holds the reason as text only.

## Next steps

> [card] [AllergyIntolerance resource group](https://docs.corti.ai/fhir/resource-groups/allergy-intolerance.md)
>
> Learn how allergies and their reactions look in FHIR.

> [card] [Filter FHIR resources](https://docs.corti.ai/fhir/filtering.md)
>
> Produce only some procedure categories, or restrict procedure codes.


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