[Alpha] Extract medical codes with phenocr

POST/construe/phenocr

Alpha: phenocr is an alpha feature. Request parameters, response shape, and results may change between releases. Do not depend on it for production workloads yet.

Extracts medical codes from natural language clinical text using phenocr.

Supported code systems: HPO, ICD-10-CM, RXNORM, and SNOMED_CT_US. The code system name and version are both required.

RequiresBearerauthentication

Body parameters

textstringrequired

Natural language text to extract codes from

systemobjectrequired

namestringrequired

Code system name. Supported by phenocr: HPO, ICD-10-CM, RXNORM, SNOMED_CT_US.

versionstringrequired

Code system version to run against.

Returns

Successfully extracted codes

Response fields

systemobjectrequired

namestringoptional

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.

versionstringoptional

Specific code system version.

codesobject[]required

codestringrequired

The extracted code

descriptionstringrequired

Short description of the code

validbooleanrequired

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.

reasonstringoptional

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

is_ancestorbooleanoptional

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

citationsobject[]optional

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.

textstringrequired

The exact text span containing evidence for the code

begin_offsetintegerrequired

Starting byte offset in the original input text (0-indexed)

end_offsetintegerrequired

Ending byte offset (exclusive), such that input[begin_offset:end_offset] == text

categoriesobject[]optional

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

uristringrequired

Identifier for the category term (e.g. an HPO URI).

labelstringrequired

Human-readable label for the category term.

POSTRequest

# Get authentication token
PHENOML_TOKEN=$(curl -X POST "https://experiment.app.pheno.ml/v2/auth/token" \
  -u "$PHENOML_CLIENT_ID:$PHENOML_CLIENT_SECRET" \
  | jq -r '.access_token')

curl -X POST "https://experiment.app.pheno.ml/construe/phenocr" \
  -H "Authorization: Bearer $PHENOML_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "5-year-old male with seizures, severe intellectual disability, microcephaly, and hypotonia.",
  "system": {
    "name": "HPO",
    "version": "umls-2026AA"
  }
}'

200 OKExample Response

{
  "system": {
    "name": "SNOMED_CT_US_LITE",
    "version": "umls-2026aa"
  },
  "codes": [
    {
      "code": "195967001",
      "description": "Asthma",
      "valid": true,
      "reason": "example",
      "is_ancestor": true,
      "citations": [
        {
          "text": "Patient has type 2 diabetes",
          "begin_offset": 0,
          "end_offset": 27
        }
      ],
      "categories": [
        {
          "uri": "HP:0025142",
          "label": "Constitutional symptom"
        }
      ]
    }
  ]
}