Terminology Crosswalk

FHIR-native SNOMED CT, CPT, and ICD-10-CM code translation for CMS-0057 compliance. The crosswalk bridges the terminology gap between Da Vinci clinical workflows and payer claims adjudication systems.

1. Overview

The CMS Interoperability and Prior Authorization Final Rule (CMS-0057-F) requires payers to support Da Vinci CRD, DTR, and PAS workflows. These workflows exchange clinical data encoded in SNOMED CT — the standard used by EHRs and clinical decision support systems. But payer core administration platforms (QNXT, Facets, HealthEdge, and others) store and adjudicate claims using CPT and ICD-10-CM codes.

The CHO Terminology Crosswalk service bridges that gap. It provides a FHIR-native ConceptMap/$translate API that converts codes between SNOMED CT, CPT, and ICD-10-CM in real time — with context-aware disambiguation for one-to-many mappings.

2. How It Works

The crosswalk implements the FHIR R4 ConceptMap/$translate operation. You provide a source code system, a code, and a target code system. The service returns one or more translated codes with equivalence metadata.

Basic translation flow

# Translate SNOMED CT 73211009 (Diabetes mellitus) to ICD-10-CM
curl -s "http://localhost:5010/fhir/ConceptMap/\$translate?\
system=http://snomed.info/sct&\
code=73211009&\
targetsystem=http://hl7.org/fhir/sid/icd-10-cm" | jq .

# Response (simplified)
{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "result", "valueBoolean": true },
    {
      "name": "match",
      "part": [
        { "name": "equivalence", "valueCode": "narrower" },
        { "name": "concept", "valueCoding": {
            "system": "http://hl7.org/fhir/sid/icd-10-cm",
            "code": "E11.9",
            "display": "Type 2 diabetes mellitus without complications"
        }},
        { "name": "score", "valueDecimal": 0.85 }
      ]
    }
  ]
}

Context-aware disambiguation

Many SNOMED CT concepts map to multiple ICD-10-CM codes. For example, SNOMED 73211009 (Diabetes mellitus) can map to E10.x (Type 1), E11.x (Type 2), E13.x (Other specified), or O24.x (Gestational). The crosswalk uses clinical context to disambiguate:

Context Parameter	Effect	Example
patient.age	Selects age-appropriate codes	Pediatric vs. adult diabetes codes
patient.gender	Excludes gender-impossible codes	Prostate conditions excluded for female patients
patient.state	Applies state-specific rules	Texas TMPPM coding conventions
patient.conditions	Co-morbidity-aware selection	Diabetes with CKD selects E11.22 over E11.9

# Context-aware translation — include patient details for disambiguation
curl -s -X POST http://localhost:5010/fhir/ConceptMap/\$translate \
  -H "Content-Type: application/fhir+json" \
  -H "X-Tenant-ID: demo" \
  -d '{
    "resourceType": "Parameters",
    "parameter": [
      { "name": "system", "valueUri": "http://snomed.info/sct" },
      { "name": "code", "valueCode": "73211009" },
      { "name": "targetsystem", "valueUri": "http://hl7.org/fhir/sid/icd-10-cm" },
      { "name": "context-age", "valueInteger": 12 },
      { "name": "context-gender", "valueCode": "male" },
      { "name": "context-state", "valueCode": "TX" },
      { "name": "context-conditions", "valueString": "chronic-kidney-disease" }
    ]
  }' | jq .

3. Data Sources

The crosswalk aggregates maps from three tiers, each with different licensing and update cadences:

Source	Mapping Direction	Entries	License	Update Cadence
NLM / UMLS	SNOMED CT → ICD-10-CM	~119,000	Free (UMLS license)	Twice yearly (March, September)
AMA	CPT ↔ SNOMED CT	Varies	Customer-provided (bring your own license)	Annually
Plan-specific overrides	Any direction	Varies	Tenant-scoped	As needed

NLM / UMLS maps

The National Library of Medicine publishes the official SNOMED CT to ICD-10-CM mapping tables as part of the UMLS distribution. These maps are free to use under a UMLS license and contain approximately 119,000 entries. They are distributed in RF2 (Release Format 2) and updated twice per year with each ICD-10-CM annual release and mid-year supplement.

AMA CPT cross maps

The American Medical Association publishes CPT-to-SNOMED CT cross maps. Because CPT is a proprietary code set, customers must provide their own AMA license files. Upload the CSV export through the Admin API or mount the file to the service's data volume. The crosswalk never redistributes AMA content.

Plan-specific overrides

Payers frequently maintain local coding conventions that differ from the national standard. Examples include Texas TMPPM (Texas Medicaid & CHIP Preferred Procedure Manual), state Medicaid variations, and plan-specific coding policies. Overrides are tenant-scoped — each plan can have its own override file, and overrides take the highest priority during translation.

4. Map Management

Auto-loading at startup

When the crosswalk service starts, it scans the configured data volume (/data/maps by default) for RF2 and CSV files. Recognized map files are loaded automatically. Loading is idempotent — if a map version has already been loaded (tracked by filename hash and version header), it is skipped.

Admin API for uploading maps

New map files can be uploaded at runtime without restarting the service:

# Upload an NLM RF2 map file
curl -s -X POST http://localhost:5010/admin/maps/load \
  -H "X-Tenant-ID: demo" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@tls_Icd10cmHumanReadableMap_US1000124_20250301.txt" \
  -F "format=rf2" \
  -F "source=nlm" | jq .

# Upload an AMA CSV cross map
curl -s -X POST http://localhost:5010/admin/maps/load \
  -H "X-Tenant-ID: demo" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@cpt-snomed-crossmap-2025.csv" \
  -F "format=csv" \
  -F "source=ama" | jq .

# Upload plan-specific overrides (tenant-scoped)
curl -s -X POST http://localhost:5010/admin/maps/load \
  -H "X-Tenant-ID: acme-health" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@acme-overrides-2025-q1.csv" \
  -F "format=csv" \
  -F "source=override" | jq .

Version tracking and audit trail

Every loaded map is assigned a version record that includes the filename, SHA-256 hash, source type, entry count, and load timestamp. Every translation response includes a map-version extension so downstream consumers can trace exactly which map version produced a given translation. This is critical for audit and compliance.

# List all loaded map versions
curl -s http://localhost:5010/admin/maps \
  -H "X-Tenant-ID: demo" | jq .

# Example response
{
  "maps": [
    {
      "id": "map-nlm-20250301",
      "source": "nlm",
      "format": "rf2",
      "version": "US1000124_20250301",
      "entries": 119423,
      "loadedAt": "2026-03-26T08:15:00Z",
      "sha256": "a1b2c3d4..."
    },
    {
      "id": "map-ama-2025",
      "source": "ama",
      "format": "csv",
      "version": "2025.1",
      "entries": 8742,
      "loadedAt": "2026-03-26T08:15:02Z",
      "sha256": "e5f6g7h8..."
    }
  ]
}

5. Portal Integration

The Cloud Health Office portal provides a dedicated Terminology Crosswalk page at /terminology/crosswalk with four key features:

Health status dashboard

The top of the page displays real-time service health: connection status (green/red), total active map entries across all loaded maps, and the number of map files currently loaded. If the crosswalk service is unreachable, the dashboard shows a clear error state with troubleshooting guidance.

Interactive translation tester

A form where users can enter a source code system, code, and target system, then execute a live translation. The result displays all matched target codes with their equivalence level, display name, and score. Context fields (age, gender, state, conditions) are optional inputs for disambiguation testing.

Map versions table

A sortable table showing every loaded map version: source, format, version string, entry count, load timestamp, and SHA-256 hash. Administrators can use this view to verify that the correct map versions are active before going live with a configuration change.

6. Context Rule Engine

When a SNOMED CT concept maps to multiple ICD-10-CM codes, the context rule engine selects the best match. Rules are evaluated in priority order, and the narrowest matching rule wins.

Rule Type	Priority	Description	Example
Plan-specific overrides	Highest	Tenant-scoped overrides from plan coding policy	Acme Health maps 73211009 to E11.65 for all members
Co-morbidity rules	High	Require specific active conditions on the patient	Diabetes + CKD selects E11.22 over E11.9
State-specific rules	Medium	TMPPM, Medicaid state variations, local conventions	Texas Medicaid requires specific modifier codes
Gender rules	Medium	Exclude gender-impossible ICD-10-CM codes	Prostate conditions excluded for female patients
Age rules	Standard	Pediatric vs. adult code selection	Juvenile diabetes (E10.x) for patients under 18

Scoring

Each rule that matches adds to the candidate code's score. Narrower rules (those with more specific criteria) contribute higher score values. When multiple candidate codes remain after rule evaluation, the code with the highest aggregate score is returned as the primary match. All other candidates are returned as secondary matches with lower scores, allowing consumers to make their own selection if needed.

7. API Reference

All endpoints require the X-Tenant-ID header. FHIR endpoints accept and return application/fhir+json.

GET /fhir/ConceptMap/$translate

Single code translation via query parameters.

Parameter	Type	Required	Description
system	uri	Yes	Source code system (e.g., http://snomed.info/sct)
code	string	Yes	Source code value
targetsystem	uri	Yes	Target code system (e.g., http://hl7.org/fhir/sid/icd-10-cm)
context-age	integer	No	Patient age in years
context-gender	code	No	Patient gender (male, female, other)
context-state	code	No	Two-letter US state code
context-conditions	string	No	Comma-separated active condition codes

POST /fhir/ConceptMap/$translate

Single code translation via structured FHIR Parameters resource in the request body. Supports the same context parameters as the GET variant. Preferred for complex requests with multiple context values.

POST /fhir/ConceptMap/$batch-translate

Bulk translation of up to 500 codes in a single request. The request body is a FHIR Bundle of Parameters resources. Each entry is translated independently and the response is a Bundle of translation results in the same order.

# Batch translate 3 SNOMED codes to ICD-10-CM
curl -s -X POST http://localhost:5010/fhir/ConceptMap/\$batch-translate \
  -H "Content-Type: application/fhir+json" \
  -H "X-Tenant-ID: demo" \
  -d '{
    "resourceType": "Bundle",
    "type": "batch",
    "entry": [
      {
        "resource": {
          "resourceType": "Parameters",
          "parameter": [
            { "name": "system", "valueUri": "http://snomed.info/sct" },
            { "name": "code", "valueCode": "73211009" },
            { "name": "targetsystem", "valueUri": "http://hl7.org/fhir/sid/icd-10-cm" }
          ]
        }
      },
      {
        "resource": {
          "resourceType": "Parameters",
          "parameter": [
            { "name": "system", "valueUri": "http://snomed.info/sct" },
            { "name": "code", "valueCode": "386661006" },
            { "name": "targetsystem", "valueUri": "http://hl7.org/fhir/sid/icd-10-cm" }
          ]
        }
      },
      {
        "resource": {
          "resourceType": "Parameters",
          "parameter": [
            { "name": "system", "valueUri": "http://snomed.info/sct" },
            { "name": "code", "valueCode": "195967001" },
            { "name": "targetsystem", "valueUri": "http://hl7.org/fhir/sid/icd-10-cm" }
          ]
        }
      }
    ]
  }' | jq .

GET /admin/maps

List all loaded map versions for the current tenant. Returns source, format, version, entry count, load timestamp, and SHA-256 hash for each map.

POST /admin/maps/load

Upload a new map file. Accepts multipart/form-data with the following fields:

Field	Type	Required	Description
file	file	Yes	The map file (RF2 or CSV)
format	string	Yes	rf2 or csv
source	string	Yes	nlm, ama, or override

8. Consumer Integration

Three core CHO services consume the Terminology Crosswalk at runtime:

CRD Server (Coverage Requirements Discovery)

When a CRD hook fires, the CRD server receives SNOMED CT codes from the EHR. It calls the crosswalk to translate them into the payer's CPT/ICD-10-CM code space, then checks those codes against the plan's benefit configuration to determine whether prior authorization is required. Without the crosswalk, the CRD server cannot match clinical codes to payer business rules.

PAS Server (Prior Authorization Support)

The PAS server receives X12 278 prior authorization requests and converts them to FHIR. During this conversion, procedure and diagnosis codes may need to be translated between code systems. The PAS server uses the $batch-translate endpoint to convert all codes in a single round trip, keeping latency low for real-time prior auth decisions.

DTR Engine (Documentation Templates and Rules)

Da Vinci DTR questionnaires may reference codes in a different system than the one used by the EHR. The DTR engine uses the crosswalk to resolve questionnaire answer codes so that pre-populated values match the expected code system in each question. This ensures that auto-populated questionnaire responses are clinically accurate and machine-readable.