Skip to main content

ConceptMap $translate

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​

NameTypeDescriptionRequired
urluriCanonical URL of the ConceptMap, if not specified by IDNo
sourceuriCanonical URL of source ValueSet, used to look up ConceptMapNo
codecodeCode to translate using the ConceptMapNo
systemuriSystem the code (above) is drawn fromNo
codingCodingFull coding to translate using the ConceptMapNo
codeableConceptCodeableConceptConcept with one or more codes to translate using the ConceptMapNo
targetsystemuriTarget code system, used to filter resultsNo
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" }
    }
  ]
}