Extract medical codes from text

Code system name. Can be a built-in system or a custom system name.

Built-in systems:

• CPT
• HCPCS
• HPO
• ICD-10
• ICD-10-CM
• ICD-10-PCS
• LOINC
• RXNORM
• SNOMED_CT_US
• SNOMED_CT_US_LITE

Custom systems:

• Any valid system name uploaded via /construe/upload. Requires a paid plan.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.

Specific code system version.

Method for splitting input text into chunks before code extraction.

• none - Treat the full input as a single chunk.
• sentences - Split on sentence boundaries (supports citations).
• paragraphs / topics / soap_note - LLM-based chunking.
• clinical_ner_extract - Extract clinical concepts (problems, tests, treatments) and use each as a chunk (supports citations).
• fasthpocr - Extract HPO concepts directly with category annotations (supports citations). Requires system: HPO; other systems are rejected. Causes most other config options to be ignored.

Maximum number of codes to extract per chunk. If not specified, uses system-specific defaults:

• SNOMED: 10
• LOINC, HPO, RXNORM: 20
• All other systems: 5

Threshold for filtering similar codes (0.0-1.0)

Method for validating extracted codes:

• none - No validation, returns all candidate codes
• simple - LLM-based validation
• medication_search - LLM-based validation tailored for medication concepts
• chunk_code_jaccard_similarity - Token-level Jaccard similarity between source text chunk and code description

Minimum Jaccard similarity (0.0-1.0) for a code to be considered valid when using the "chunk_code_jaccard_similarity" validation method. Ignored by other methods.

Whether to include explanations for why each code was extracted

Whether to include ancestor/parent codes in the results

Whether to include codes that failed validation in the results

Whether to include source text citations for each extracted code. Citations show the exact text spans (with character offsets) that led to each code. Supported when chunking_method is "sentences", "clinical_ner_extract", or "fasthpocr".

Optional context describing the goal of the extraction. Required when min_context_relevance is greater than 0.

Minimum relevance score (0.0–1.0) a chunk must reach to proceed to code extraction. Chunks are scored by an LLM against the extraction_context goal. Chunks below this threshold are dropped, reducing noise and extraction cost. Set to 0 (the default) to disable relevance filtering and extract from all chunks. Requires the "extraction_context" field when set above 0.

How much effort to spend ensuring consistent results across repeated requests. Higher levels apply stricter filtering to remove borderline results that may vary between calls, improving determinism at the cost of additional latency.

When validation_method is set to a value other than "none", consistency is applied to the validation step: codes must be unanimously validated across multiple rounds to be included.

When validation_method is "none" and min_context_relevance is set above 0, consistency is applied to the relevance ranking step instead: chunks must pass the relevance threshold in every round to be included.

Code system name. Can be a built-in system or a custom system name.

Built-in systems:

• CPT
• HCPCS
• HPO
• ICD-10
• ICD-10-CM
• ICD-10-PCS
• LOINC
• RXNORM
• SNOMED_CT_US
• SNOMED_CT_US_LITE

Custom systems:

• Any valid system name uploaded via /construe/upload. Requires a paid plan.

Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.

Specific code system version.

The extracted code

Short description of the code

Whether the code passed validation. Always true unless include_invalid is set to true, in which case invalid codes will have this set to false.

Explanation for why this code was extracted (if include_rationale is true)

Whether this code is an ancestor (parent) of an extracted code rather than directly extracted. Only present when include_ancestors is true.

Source text references showing where this code was found in the input. Only present when include_citations is true and chunking method supports it. Ancestor codes do not receive citations.

Higher-level groupings the extracted code belongs to (e.g. HPO category terms). Only populated by full-extraction chunking methods such as "fasthpocr".