ConceptMap $translate | Medplum

Code Translation

Code translation enables seamless data exchange between systems that speak different "clinical languages," ensuring that a diagnosis recorded in one system can be understood and processed correctly by another.

The $translate operation converts codes from one code system to another using predefined mappings. This is essential for healthcare interoperability, where different systems use different terminologies—for example, translating SNOMED CT diagnoses to ICD-10 for billing, or mapping internal lab codes to LOINC for reporting.

Use Cases

• Billing Code Translation: Convert clinical SNOMED CT codes to ICD-10 codes for claims submission
• Lab Interface Mapping: Translate internal lab system codes to standard LOINC codes for external reporting
• EHR Integration: Map codes from one EHR's proprietary system to another during data migration or exchange
• Quality Reporting: Convert clinical codes to the specific code systems required by quality measure programs
• Cross-System Analytics: Normalize codes from multiple source systems to a common terminology for population health analysis

Invoke the $translate operation

[base]/ConceptMap/$translate

[base]/ConceptMap/[id]/$translate

Parameters

Required Parameters

Although no individual parameter for the operation is required, both of the following must be satisfied for the operation to proceed:

• Either the ConceptMap ID must be present in the request path (e.g. by calling ConceptMap/[id]/$translate), or one of url or source must be populated to look up the ConceptMap
• Exactly one of the following must be set to specify the source code(s) to translate:
  • Both code and system
  • coding
  • codeableConcept

Example

As an example, assume the following ConceptMap resource exists in the system:

{

"resourceType": "ConceptMap",

"url": "http://example.com/concept-map",

"status": "active",

"sourceCanonical": "http://example.com/labs",

"group": [
    {
      "source": "http://snomed.info/sct",
      "target": "http://loinc.org",
      "element": [
        {
          "code": "313444004",
          "target": [
            {
              "code": "15067-2",
              "display": "Follitropin Qn",
              "equivalence": "equivalent"
            }
          ]
        }
      ]
    },
    {
      "source": "http://snomed.info/sct",
      "target": "http://www.ama-assn.org/go/cpt",
      "element": [
        {
          "code": "313444004",
          "target": [{ "code": "83001", "equivalence": "equivalent" }]
        }
      ]
    }
  ]
}

To translate a code using this ConceptMap, one would make an API request like the following:

curl 'https://api.medplum.com/fhir/R4/ConceptMap/[id]/$translate' \

-X POST \

-H "Content-Type: application/fhir+json" \

-H "Authorization: Bearer $ACCESS_TOKEN" \

-d '{"resourceType":"Parameters","parameter":[ {"name":"code","valueCode":"313444004"}, {"name":"system","valueUri":"http://snomed.info/sct"} ]}'

Success Response

Example outcome:

{

"resourceType": "Parameters",

"parameter": [
    { "name": "result", "valueBoolean": true },
    {
      "name": "match",
      "part": [
        { "name": "equivalence", "valueCode": "equivalent" },
        { "name": "concept", "valueCoding": {
          "system": "http://loinc.org",
          "code": "15067-2",
          "display": "Follitropin Qn"
        }}
      ]
    },
    {
      "name": "match",
      "part": [
        { "name": "equivalence", "valueCode": "equivalent" },
        { "name": "concept", "valueCoding": {
          "system": "http://www.ama-assn.org/go/cpt",
          "code": "83001"
        }}
      ]
    }
  ]
}

Error Response

Example outcome when ambiguous input parameters are provided, e.g.:
Request:

POST /fhir/R4/ConceptMap/$translate

{

"resourceType": "Parameters",

"parameter": [
    { "name": "url", "valueCode": "http://example.com/concept-map" },
    { "name": "code", "valueCode": "foo" },
    { "name": "system", "valueUri": "http://example.com/code-system" },
    { "name": "coding", "valueCoding": { "code": "bar", "system": "http://example.com/code-system" } }
  ]
}

Response:

400 Bad Request

{

"resourceType": "OperationOutcome",

"issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": { "text": "Ambiguous input: multiple source codings provided" }
    }
  ]
}