Concept maps
Translating a code from one vocabulary into another — the ICD-11 to ICD-10 crosswalk and everything shaped like it. Taught in Translating between vocabularies.
Find the map you need
Filter by source_code_system and target_code_system (numeric ids), by canonical_url, or by short_code. More than one map can share a canonical url, so the caller picks. Public for published maps.
Keep from the response: the map id
Answers without a credential. What you see is what is published publicly, so an emptier list than you expected is scope rather than absence.
query Parameters
source_code_systemNumeric id of the system you are translating from.
target_code_systemNumeric id of the system you are translating to.
canonical_urlResolve a map from the identity a FHIR payload carries.
page_sizeResults per page. A sync that reads only page one ships a fraction of a vocabulary and looks like it worked.
pagePage number. Follow next in the response rather than computing this.
Find the map you need › Responses
Returns the map id.
Every row in the map
Filterable by equivalence and by mapped. This is where you see a positive no-mapping declaration — a row with no_map: true and a no_map_reason, meaning somebody decided this code deliberately has no target. $translate cannot show you that: it excludes such rows, so it answers result: false exactly as it would for a code nobody has looked at.
Keep from the response: target_code, equivalence, no_map
path Parameters
concept_mapThe concept map, addressed by its short code (recommended) or its numeric id.
Resolution is pk-first: a value that looks numeric is tried as an id, and falls through to the code column when no row matches, so an all-digits short code is still reachable. Codes are matched case-insensitively after an exact miss. The one ambiguity — a short code identical to some other row's id — resolves to the id.
Example: ICD11-TO-ICD10.
query Parameters
equivalenceOne of equivalent, narrower, broader, related, notrelated, nomap, unmapped. (wider and unmatched are accepted legacy spellings of broader and notrelated.)
mappedRestrict to rows that do, or do not, carry a target.
page_sizeResults per page. A sync that reads only page one ships a fraction of a vocabulary and looks like it worked.
pagePage number. Follow next in the response rather than computing this.
Every row in the map › Responses
Returns target_code, equivalence, no_map.
Translate one code
Returns a FHIR Parameters resource: result, plus one match per mapped target carrying an equivalence and the target Coding. Rows declared no_map and rows with a blank target are excluded — they are not translations. A result: false therefore means either “unknown code” or “deliberately mapped to nothing”, and this operation cannot tell you which — read /entries/ when the difference matters.
Keep from the response: the target code, and its equivalence
path Parameters
concept_mapThe concept map, addressed by its short code (recommended) or its numeric id.
Resolution is pk-first: a value that looks numeric is tried as an id, and falls through to the code column when no row matches, so an all-digits short code is still reachable. Codes are matched case-insensitively after an exact miss. The one ambiguity — a short code identical to some other row's id — resolves to the id.
Example: ICD11-TO-ICD10.
query Parameters
codeThe source code to translate. Required.
versionWhich version of the artefact this read serves.
serving— the version the artefact currently resolves to: the author's or regulator'sMANUALpin if one is set, otherwise the newest released version effective today. This is what an integration should send.- a released version's
version_id(v1.0.0) or its numeric id — exactly that frozen release. Only released versions are honoured; an unknown or unreleased reference falls back to the working copy with a warning rather than failing. draft— the pending draft, for reviewers. Requires the reviewer permission.
Omitted, what you get depends on the artefact: the working copy including drafts while it is unpinned, or the pinned version if an owner has set one. That is what an authoring client wants and the opposite of what a consumer wants — the problem is not that it is always live, but that you cannot tell which you got.
One exception to serving meaning frozen, and it is silent: a code system release predating the content-versioning backfill carries no ordinal, so the read serves the live working copy at 200 with no signal in the body or headers. Detect it on the artefact instead — a released version whose ladder row has sequence: null has no frozen content to serve.
A pinned read is cacheable indefinitely (Cache-Control: immutable); an unversioned one is no-cache, because its content changes on release with no write to the rows it would be cached on.
Translate one code › Responses
Returns the target code, and its equivalence.
resourceTypeThe whole map as FHIR
The FHIR R4 ConceptMap resource, for loading a crosswalk into your own terminology client rather than calling $translate per code.
Keep from the response: the bundle
path Parameters
concept_mapThe concept map, addressed by its short code (recommended) or its numeric id.
Resolution is pk-first: a value that looks numeric is tried as an id, and falls through to the code column when no row matches, so an all-digits short code is still reachable. Codes are matched case-insensitively after an exact miss. The one ambiguity — a short code identical to some other row's id — resolves to the id.
Example: ICD11-TO-ICD10.
The whole map as FHIR › Responses
Returns the bundle.