Skip to navigation
Guides

Enrichment with clinical context

Problem-domain matching that weighs the patient, not just the string.

POST /precision/normalize/enrichment is a Problem-domain-only engine that applies enhanced AI models and prioritizes the clinical context you pass with each record.

Enrichment accepts only domain: "Problem". For every other domain use normalize.

Why context matters

hypertension in a 4-year-old and hypertension in a 78-year-old are not clinically the same problem. The standard engine matches the string; enrichment weighs the patient.

const result = await client.normalize.enrich({
  clientRequestId: "enrich-001",
  preferences: { threshold: 0.6, size: 3 },
  requests: [
    {
      recordId: "1",
      domain: "Problem",
      inputTerm: "shortness of breath on exertion",
      context: {
        age: 71,
        sex: "M",
        icd10Codes: ["I50.9", "J44.9"],
        sourceText:
          "Patient reports increasing dyspnea climbing one flight of stairs.",
      },
    },
  ],
});

Context fields

age
integer

Patient age in years. Drives age-appropriate lexical selection — the response metadata’s age_indicator flag reports which band was applied.

sex
enum

M or F. Filters sex-specific problems and surfaces the sex_indicator flag.

icd10_codes
string[]

The patient’s existing ICD-10 codes. Comorbidity history is the single highest- leverage context field — pass it whenever you have it.

source_text
string

The surrounding clinical narrative the term was extracted from. Gives the model the sentence-level context a bare term loses.

use_count
integer

How often your users have previously selected this term. Nudges ranking toward what your population actually means.

Provenance fields

application_id, facility_id, encounter_id, document_id, and project_id are optional identifiers echoed back in the response. They don’t affect matching — they exist so you can trace a normalization back to where it originated.

Reading the result

The response mirrors normalize, with context echoed back on each record so you can confirm what the model actually considered:

{
  "summary": { "count": 1, "error_count": 0 },
  "client_request_id": "enrich-001",
  "requests": [
    {
      "record_id": "1",
      "domain": "Problem",
      "input_term": "shortness of breath on exertion",
      "context": { "age": 71, "sex": "M", "icd10_codes": ["I50.9", "J44.9"] },
      "response": {
        "match_field": "input_term",
        "match_includes_assumptions": true,
        "explanation": "Matched with consideration of documented heart failure and COPD.",
        "items": [
          {
            "lexical_code": "48291",
            "lexical_title": "Dyspnea on exertion",
            "score": 0.94,
            "certainty": "High"
          }
        ]
      }
    }
  ]
}

response.match_includes_assumptions is your audit signal: when true, the engine inferred something beyond the literal input. Pair it with explanation when surfacing results to clinicians for review.

Choosing an engine

UseEngine
Any domain other than Problemnormalize
Bulk code-to-code translationnormalize (code-based)
Custom lexical mapsnormalize
Problem terms with patient context availableenrich
Ambiguous free text from notesenrich