Crosswalk a code to target code systems

POST/construe/codes/crosswalk

Maps one source medical code to one or more target code-system URIs using shared UMLS CUIs. A successful response is HTTP 200 even when the source code or a target has no matches; inspect reason_code on the item and target entries for miss details.

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

RequiresBearerauthentication

Body parameters

systemstringrequired

Source FHIR code-system URI.

codestringrequired

Source code to map.

targetsstring[]required

Target FHIR code-system URIs.

Returns

Crosswalk result for the source code

Response fields

resolved_umls_releasestringrequired

UMLS release used for the crosswalk.

systemstringrequired

Source FHIR code-system URI.

codestringrequired

Source code that was mapped.

reason_codestringoptional

Item-level reason code when the source code could not be mapped.

targetsobject[]required

Crosswalk matches grouped by requested target code-system URI.

systemstringrequired

Target FHIR code-system URI.

reason_codestringoptional

Target-level reason code when this target has no matches.

matchesobject[]required

Codes in this target system that share a UMLS CUI with the source code.

codestringrequired

Matched code in the target system.

displaystringrequired

Human-readable target code display.

cuistringrequired

UMLS CUI that links the source and target code.

suppressstringoptional

UMLS suppressibility flag, when present.

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/codes/crosswalk" \
  -H "Authorization: Bearer $PHENOML_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "system": "http://hl7.org/fhir/sid/icd-10-cm",
  "code": "A02.24",
  "targets": [
    "http://human-phenotype-ontology.org"
  ]
}'

200 OKExample Response

{
  "resolved_umls_release": "2026AA",
  "system": "http://hl7.org/fhir/sid/icd-10-cm",
  "code": "A02.24",
  "targets": [
    {
      "system": "http://human-phenotype-ontology.org",
      "matches": [
        {
          "code": "HP:0005661",
          "display": "Salmonella infection",
          "cui": "C0036111"
        }
      ]
    }
  ]
}