Advanced Usage

Filter the prediction set

Use the optional filter field to restrict which codes the model may predict. include and exclude each take a list of condition objects:

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

For example, to predict 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" }
  ]
}

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

Some coding systems support filtering on additional attributes beyond code. For example, SNOMED CT concepts can be filtered 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.

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 — for example, a semantic_tag condition when also requesting CPT — that system fails validation and the entire request is rejected, not just that system. No prediction is attempted when validation fails. See Errors for the general error response shape.

Omit the filter field for open-ended prediction: the API will predict across the full coding system.

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

Code Prediction

Coding Systems

Use Cases

Filter the prediction set

Filter validation

​Filter the prediction set

​Filter validation

Filter the prediction set

Filter validation