Code filtering

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

{
  "filters": [
    {
      "systemId": "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
`systemId`	`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.

The final prediction set is the include set minus the exclude set.

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

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.

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`

CPT has no code hierarchy, so it only supports = and in on code. Using is-a or descendent-of on CPT returns a 400 error.

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.

Examples

AND: match all

SNOMED-CT

Predict diabetes mellitus SNOMED-CT codes AND limit results to codes with semantic tag “disorder”

{
  "filters": [
    {
      "systemId": "snomedctint",
      "include": {
        "match": "all",
        "conditions": [
          { "property": "code", "op": "is-a", "value": "73211009" },
          { "property": "semantic_tag", "op": "=", "value": "disorder" }
        ]
      }
    }
  ]
}

OR: match any

SNOMED-CT

Predict SNOMED-CT codes for diabetes OR any procedure codes

{
  "filters": [
    {
      "systemId": "snomedctint",
      "include": {
        "match": "any",
        "conditions": [
          { "property": "code", "op": "is-a", "value": "73211009" },
          { "property": "semantic_tag", "op": "=", "value": "procedure" }
        ]
      }
    }
  ]
}

Nested groups: mixed AND/OR

SNOMED-CT

Predict SNOMED-CT codes for diabetes disorders OR hypertension findings

{
  "filters": [
    {
      "systemId": "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" }
            ]
          }
        ]
      }
    }
  ]
}

Specific inclusion/exclusion criteria

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)

{
  "filters": [
    {
      "systemId": "icd10cm-outpatient",
      "include": {
        "conditions": [
          { "property": "code", "op": "is-a", "value": "E11" }
        ]
      },
      "exclude": {
        "conditions": [
          { "property": "code", "op": "in", "value": ["E11.00", "E11.01"] }
        ]
      }
    }
  ]
}

Hierarchy filtering

ICD-10

Predict ICD-10 codes for diabetes mellitus (E11), but do not include results that are descendants of diabetes with hyperosmolarity (E11.0)

{
  "filters": [
    {
      "systemId": "icd10cm-outpatient",
      "include": {
        "conditions": [
          { "property": "code", "op": "is-a", "value": "E11" }
        ]
      },
      "exclude": {
        "conditions": [
          { "property": "code", "op": "descendent-of", "value": "E11.0" }
        ]
      }
    }
  ]
}

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:

{
  "filters": [
    {
      "systemId": "snomedctint",
      "include": {
        "conditions": [
          { "property": "semantic_tag", "op": "in", "value": ["disorder", "finding"] }
        ]
      }
    }
  ]
}

See SNOMED CT for the full list of supported semantic_tag values.

Multi-system requests

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:

{
  "filters": [
    {
      "systemId": "snomedctint",
      "include": {
        "conditions": [
          { "property": "semantic_tag", "op": "in", "value": ["disorder", "finding"] }
        ]
      }
    },
    {
      "systemId": "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.

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, or on a system without a code hierarchy (CPT).
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.

When requesting multiple coding systems, each system validates only its own filter. A filter whose systemId isn’t in the system field is rejected with a 400 error. If a system has no corresponding filter object, no filtering is applied to it.

Error response

{
  "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 for the full error response shape.

Please contact us if you need help configuring your requests or have questions about advanced usage.

Clinical Text Generation

Medical Coding

Clinical Assistant

Condition groups

Conditions

Filterable properties

Examples

AND: match all

OR: match any

Nested groups: mixed AND/OR

Specific inclusion/exclusion criteria

Hierarchy filtering

Multi-system requests

Empty filter

Filter validation

Error response

​Condition groups

​Conditions

​Filterable properties

​Examples

​AND: match all

​OR: match any

​Nested groups: mixed AND/OR

​Specific inclusion/exclusion criteria

​Hierarchy filtering

​Multi-system requests

​Empty filter

​Filter validation

​Error response

Condition groups

Conditions

Filterable properties

Examples

AND: match all

OR: match any

Nested groups: mixed AND/OR

Specific inclusion/exclusion criteria

Hierarchy filtering

Multi-system requests

Empty filter

Filter validation

Error response