Code filtering

Filter code prediction output

Use the optional filter field to restrict which codes the model may predict. The include and exclude objects take a list of conditions used to constrain prediction output:

include: codes matching all of these conditions are eligible. Empty or omitted means every code in the system is eligible.
exclude: codes matching all of these conditions are removed from the eligible set. Empty or omitted means nothing is removed.

The final prediction set is the include set minus the exclude set. 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.

op supports:

Operator	Matches
`=`	The property equals `value`.
`is-a`	The code itself or any of its descendants.
`descendent-of`	A strict descendant of the code (excludes the code itself).
`exists`	Whether the property is set. `value: true` matches when it has a value; `value: false` matches when it doesn’t.
`in`	The property’s value is one of the values in `value`.

Conditions defined in include/exclude are AND-combined. To match alternatives, list them in one condition’s value instead of adding separate conditions. Use op: "in" for exact values or op: "is-a" with multiple ancestor codes where supported.

Examples

ICD-10

Limit code predict results to type 2 diabetes mellitus (E11) and its descendants, but never the specific code for diabetes with hyperosmolarity (E11.00):

"filter": {
  "include": [
    { "property": "code", "op": "is-a", "value": ["E11"] }
  ],
  "exclude": [
    { "property": "code", "op": "=", "value": "E11.00" }
  ]
}

SNOMED-CT

Filter SNOMED-CT concepts by semantic_tag, the clinical category a concept belongs to:

"filter": {
  "include": [
    { "property": "semantic_tag", "op": "in", "value": ["disorder", "finding"] }
  ]
}

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

Omit the filter field for open-ended prediction: the API will predict 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.

When requesting multiple coding systems, the same filter applies to all of them.If a condition doesn’t apply to one of the requested systems (e.g., a semantic_tag condition when requesting both SNOMED-CT and CPT), then that system fails validation and the entire request is rejected.

No prediction is attempted when validation fails. See Errors for the general error response shape.

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

Endpoints

Features

Coding Systems

Guides

Filter code prediction output

Examples

Filter validation

​Filter code prediction output

​Examples

​Filter validation

Filter code prediction output

Examples

Filter validation