Translate a concept using a ConceptMap

$translate searches for target concepts mapped from a source code. It uses a ConceptMap and other terminology knowledge available to the server. A translation can return multiple matches; check each match's equivalence before using it.

Method	Path
GET or POST	/fhir/R4/ConceptMap/$translate

Provide exactly one source code representation: code with system, coding, or codeableConcept. Provide a source ValueSet when known, and identify the desired target with target or targetsystem.

GET request

This example maps the FHIR composition status preliminary to the target v3 ActStatus ValueSet:

curl --get 'https://api.sandbox.ovok.com/fhir/R4/ConceptMap/$translate' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --data-urlencode 'system=http://hl7.org/fhir/composition-status' \
  --data-urlencode 'code=preliminary' \
  --data-urlencode 'source=http://hl7.org/fhir/ValueSet/composition-status' \
  --data-urlencode 'target=http://hl7.org/fhir/ValueSet/v3-ActStatus'

POST request

Use a FHIR Parameters body for structured requests:

curl --request POST \
  --url 'https://api.sandbox.ovok.com/fhir/R4/ConceptMap/$translate' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/fhir+json' \
  --data @translate-concept-parameters.json

Example translate-concept-parameters.json:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "coding",
      "valueCoding": {
        "system": "http://hl7.org/fhir/composition-status",
        "code": "preliminary"
      }
    },
    {
      "name": "source",
      "valueUri": "http://hl7.org/fhir/ValueSet/composition-status"
    },
    {
      "name": "target",
      "valueUri": "http://hl7.org/fhir/ValueSet/v3-ActStatus"
    }
  ]
}

Successful response

The operation returns a Parameters resource containing the overall result and zero or more matches.

Response path	Example	Meaning
resourceType	Parameters	FHIR wrapper for the operation output.
parameter[name=result].valueBoolean	true	True when at least one returned match is acceptable.
parameter[name=match].part[name=equivalence].valueCode	equivalent	Describes how closely the source and target concepts correspond. Inspect this before using a match.
parameter[name=match].part[name=concept].valueCoding	http://hl7.org/fhir/v3/ActStatus / active	Translated code and its system. A response can contain multiple matches, including excluded or non-equivalent codes.
parameter[name=message].valueString	Optional	Warning or explanation, when present. Other match parts can describe mapping dependencies or products.

If no applicable ConceptMap can be resolved, the server may return a FHIR OperationOutcome.

Reference: HL7 FHIR R4 ConceptMap $translate.