Text search (keyword-based)

GET/construe/codes/{codesystem}/search/text

Performs fast full-text search over code IDs and descriptions.

Availability: This endpoint is only available for built-in code systems. Custom code systems uploaded via /construe/upload are not indexed for full-text search and will return empty results. Use /search/semantic to search custom code systems.

When to use: Best for autocomplete UIs, code lookup, or when users know part of the code ID or specific keywords. Fast response times suitable for typeahead interfaces.

Features:

Substring matching on code IDs (e.g., "11.65" finds "E11.65")
Typo tolerance on descriptions (not on code IDs)
Fast response times (~10-50ms)

Examples:

Query "E11" finds all codes starting with E11 (diabetes codes)
Query "diabtes" (typo) still finds "diabetes" codes

Trade-offs: Faster than semantic search, but only matches keywords/substrings. Won't find conceptually related codes with different terminology.

See also: /search/semantic for finding conceptually similar codes.

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

RequiresBearerauthentication

Path parameters

codesystemstringrequired

Code system name

Query parameters

qstringrequired

Search query (searches code IDs and descriptions)

versionstringoptional

Specific version of the code system, such as umls-2026aa.

limitintegeroptionaldefault 20

Maximum number of results (default 20, max 100)

Returns

Text search results

Response fields

systemobjectrequired

namestringrequired

Code system name

versionstringrequired

Code system version

resultsobject[]required

Codes matching the search query

codestringrequired

descriptionstringrequired

foundintegerrequired

Total number of matching results (may exceed results array due to pagination)

GETRequest

# 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 GET "https://experiment.app.pheno.ml/construe/codes/ICD-10-CM/search/text?q=E11.65&limit=5" \
  -H "Authorization: Bearer $PHENOML_TOKEN"

200 OKExample Response

{
  "system": {
    "name": "ICD-10-CM",
    "version": "2025"
  },
  "results": [
    {
      "code": "E11.65",
      "description": "Type 2 diabetes mellitus with hyperglycemia"
    },
    {
      "code": "E11.649",
      "description": "Type 2 diabetes mellitus with hypoglycemia without coma"
    },
    {
      "code": "E11.69",
      "description": "Type 2 diabetes mellitus with other specified complication"
    }
  ],
  "found": 3
}