# Translate a concept using a ConceptMap

Canonical page: https://docs.ovok.com/primitives/translate-concept

`$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 [#get-request]

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

```bash
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 [#post-request]

Use a FHIR `Parameters` body for structured requests:

```bash
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`:

```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 [#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`](https://hl7.org/fhir/R4/conceptmap-operation-translate.html).
