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

# Code filtering

> Restrict which codes the model may predict using filters.

For example, limit predictions to diabetes codes and their descendants:

```json theme={null}
{
  "filters": [
    {
      "system_id": "icd10cm-outpatient",
      "include": {
        "conditions": [
          { "property": "code", "op": "is-a", "value": "E11" }
        ]
      }
    }
  ]
}
```

The optional `filters` field accepts a list of system-scoped filter objects, one per coding system:

| Field | Type | Required | Description |
| - | - | - | - |
| `system_id` | `string` | Yes | The coding system this filter applies to (e.g. `"snomedctint"`, `"icd10cm-outpatient"`). Must match one of the systems in the `system` field. |
| `include` | ConditionGroup | No | Codes matching this group of conditions are eligible. Omitted means every code in the system is eligible. |
| `exclude` | ConditionGroup | No | Codes matching this group of conditions are removed from the eligible set. Omitted means nothing is removed. |

<Tip>The final prediction set is the include set minus the exclude set.</Tip>

***

## Condition groups

The condition groups used in `include` and `exclude` combine conditions with AND or OR logic. A `ConditionGroup` has two fields:

| Field | Type | Required | Description |
| - | - | - | - |
| `match` | `"all"` or `"any"` | No | `"all"` ANDs conditions (every condition must match). `"any"` ORs them (at least one must match). Omit when `conditions` has a single element. |
| `conditions` | array of Condition or ConditionGroup | Yes (min 1) | Conditions or nested groups combined per `match`. Maximum nesting depth: 3. |

***

## Conditions

Each condition has the following fields:

| Parameter | Description |
| - | - |
| `property` | The attribute to filter on, for example `code` (matches the `code` field on predicted codes). |
| `op` | Comparison operator, one of `=`, `is-a`, `descendent-of`, `exists`, `in`. Defaults to `=`. |
| `value` | Comparison value. Type depends on `op`. |

`op` supports:

| Operator | Matches | Value type | Properties |
| - | - | - | - |
| `=` | The property equals `value`. | `string` | All |
| `is-a` | The code itself or any of its descendants (transitive, includes self). | `string` or `string[]` | `code` only |
| `descendent-of` | A strict descendant of the code (excludes the code itself). | `string` or `string[]` | `code` only |
| `exists` | Whether the property is set. `value: true` matches when it has a value; `value: false` matches when it doesn't. | `boolean` | All |
| `in` | The property's value is one of the values in `value`. | `string[]` | All |

<Info>
  * `is-a` and `descendent-of` only apply to the `code` property. Using them on any other property returns a 400 error.
  * `is-a` and `in` accept arrays, so use `value: ["E11", "E13"]` instead of `match: "any"` with multiple conditions on the same property.
</Info>

### Filterable properties

| Property | Systems | Valid values | Operators |
| - | - | - | - |
| `code` | All systems | Any code in the system | `=`, `is-a`, `descendent-of`, `in` |
| `semantic_tag` | SNOMED CT | `disorder`, `finding`, `procedure`, `regime/therapy` | `=`, `in`, `exists` |
| `chapter_id` | ICD-10 systems | Chapter codes (e.g. `I`, `IX`) | `=`, `in`, `exists` |
| `block_id` | ICD-10 systems | Block range codes (e.g. `A00-A09`) | `=`, `in`, `exists` |

<Note>Additional properties exist on some systems' code models but are not officially supported and may change. If you need to filter on a property not listed here, [contact us](mailto:help@corti.ai).</Note>

***

## Examples

### AND: match all

<Accordion title="SNOMED-CT">
  > *Predict diabetes mellitus SNOMED-CT codes AND limit results to codes with semantic tag "disorder"*

  ```json theme={null}
  {
    "filters": [
      {
        "system_id": "snomedctint",
        "include": {
          "match": "all",
          "conditions": [
            { "property": "code", "op": "is-a", "value": "73211009" },
            { "property": "semantic_tag", "op": "=", "value": "disorder" }
          ]
        }
      }
    ]
  }
  ```
</Accordion>

### OR: match any

<Accordion title="SNOMED-CT">
  > *Predict SNOMED-CT codes for diabetes OR any procedure codes*

  ```json theme={null}
  {
    "filters": [
      {
        "system_id": "snomedctint",
        "include": {
          "match": "any",
          "conditions": [
            { "property": "code", "op": "is-a", "value": "73211009" },
            { "property": "semantic_tag", "op": "=", "value": "procedure" }
          ]
        }
      }
    ]
  }
  ```
</Accordion>

### Nested groups: mixed AND/OR

<Accordion title="SNOMED-CT">
  > *Predict SNOMED-CT codes for diabetes disorders OR hypertension findings*

  ```json theme={null}
  {
    "filters": [
      {
        "system_id": "snomedctint",
        "include": {
          "match": "any",
          "conditions": [
            {
              "match": "all",
              "conditions": [
                { "property": "code", "op": "is-a", "value": "73211009" },
                { "property": "semantic_tag", "op": "=", "value": "disorder" }
              ]
            },
            {
              "match": "all",
              "conditions": [
                { "property": "code", "op": "is-a", "value": "38341003" },
                { "property": "semantic_tag", "op": "=", "value": "finding" }
              ]
            }
          ]
        }
      }
    ]
  }
  ```
</Accordion>

### Specific inclusion/exclusion criteria

<Accordion title="ICD-10-CM">
  > *Limit code predict results to type 2 diabetes mellitus (`E11`) and its descendants, but never the specific code for diabetes with hyperosmolarity (`E11.00`) or diabetes with hyperosmolarity with coma (`E11.01`)*

  ```json theme={null}
  {
    "filters": [
      {
        "system_id": "icd10cm-outpatient",
        "include": {
          "conditions": [
            { "property": "code", "op": "is-a", "value": "E11" }
          ]
        },
        "exclude": {
          "conditions": [
            { "property": "code", "op": "in", "value": ["E11.00", "E11.01"] }
          ]
        }
      }
    ]
  }
  ```
</Accordion>

### Hierarchy filtering

<Accordion title="ICD-10">
  > *Predict ICD-10 codes for diabetes mellitus (`E11`), but do not include results that are descendants of diabetes with hyperosmolarity (`E11.0`)*

  ```json theme={null}
  {
    "filters": [
      {
        "system_id": "icd10cm-outpatient",
        "include": {
          "conditions": [
            { "property": "code", "op": "is-a", "value": "E11" }
          ]
        },
        "exclude": {
          "conditions": [
            { "property": "code", "op": "descendent-of", "value": "E11.0" }
          ]
        }
      }
    ]
  }
  ```
</Accordion>

<Accordion title="SNOMED-CT">
  Filter SNOMED-CT concepts by `semantic_tag`, the clinical category a concept belongs to. Use `op: "in"` to restrict predictions to one or more categories:

  ```json theme={null}
  {
    "filters": [
      {
        "system_id": "snomedctint",
        "include": {
          "conditions": [
            { "property": "semantic_tag", "op": "in", "value": ["disorder", "finding"] }
          ]
        }
      }
    ]
  }
  ```

  See [SNOMED CT](/coding/snomed-ct#filter-by-attribute) for the full list of supported `semantic_tag` values.
</Accordion>

### Multi-system requests

<Accordion title="SNOMED-CT and ICD-10-CM">
  When requesting multiple coding systems in a single request, provide one filter object per system. Each system only applies its own filter:

  ```json theme={null}
  {
    "filters": [
      {
        "system_id": "snomedctint",
        "include": {
          "conditions": [
            { "property": "semantic_tag", "op": "in", "value": ["disorder", "finding"] }
          ]
        }
      },
      {
        "system_id": "icd10cm-outpatient",
        "include": {
          "conditions": [
            { "property": "code", "op": "is-a", "value": "E11" }
          ]
        }
      }
    ]
  }
  ```

  The SNOMED-CT system only applies the `semantic_tag` filter, and the ICD-10-CM system only applies the `is-a E11` filter. Each system ignores filters scoped to other systems.
</Accordion>

### Empty filter

Omit the `filters` field entirely for open-ended prediction. The API predicts across the full coding system.

***

## Filter validation

Filter conditions are validated before prediction runs. A request is rejected with a 400 error if:

* `property` isn't a supported attribute for the coding system (`code`, or a system-specific attribute like `semantic_tag`).
* `value` doesn't match the type `op` expects: a string or list of strings for `is-a`/`descendent-of`, a boolean for `exists`, a list for `in`.
* `is-a` or `descendent-of` is used on a property other than `code`.
* A code referenced in a condition (directly, or as the ancestor in an `is-a`/`descendent-of` condition) doesn't exist in the coding system.
* An attribute value doesn't match any known value for that property (e.g. `semantic_tag` set to an unsupported value).
* A `ConditionGroup` has an empty `conditions` array.
* `ConditionGroup` nesting exceeds depth 3.

<Info>
  When requesting multiple coding systems, each system validates only its own filter. A filter for a system that isn't in the `system` field is ignored. If a system has no corresponding filter object, no filtering is applied to it.
</Info>

### Error response

```json theme={null}
{
  "requestid": "abc-123",
  "status": 400,
  "type": "bad_request",
  "detail": "Unknown filter property(ies): semantic_tag.",
  "validationErrors": []
}
```

This error is returned when a condition references a property the requested coding system does not support. For example, filtering by `semantic_tag` on ICD-10-CM or CPT fails validation because those systems do not define a `semantic_tag` attribute. See [Errors](/api-reference/errors) for the full error response shape.

<Note>Please [contact us](mailto:help@corti.ai) if you need help configuring your requests or have questions about advanced usage.</Note>


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