ICD-API FHIR Support
IMPORTANT! FHIR support is in pre-release state. There may be errors in the results and the API parameters and behaviour may change in the next releases
ICD-API FHIR implementation adds FHIR support for those software that needs to access the classification using FHIR.
ICD-API implements FHIR Release 5. The implementation is inline with the IHE profile Sharing Valuesets, Codes, and Maps (SVCM)
The base URL for the ICD-API that contains the pre-release for the FHIR support is located at the same location as the ICD-API i.e. https://id.who.int
The FHIR endpoints are located under the /fhir
CodeSystems
ICD-11 is composed of the "Foundation" as an underlying semantic structure together with multiple classifications (linearizations) derived from it. More information on this can be found at the ICD-11 Reference Guide
The Foundation and individual linearizations such as the main linearization "ICD-11 for Mortality and Morbidity Statistics" (ICD-11 MMS) are implemented as individual Code Systems in FHIR. International Classification of Functioning, Disability and Health (ICF) is also added as a linearization and hence it is provided as a CodeSystem in FHIR.
Foundation
The URL for the CodeSystem for the foundation is http://id.who.int/icd/entity.
ICD-11 MMS
The URL for the CodeSystem for ICD-11 MMS is http://id.who.int/icd/release/11/mms
ICD-11 MMS is the main statistical classification. In that sense it is the next version of ICD which contains ICD-11 codes.
International Classification of Functioning, Disability and Health (ICF)
The url for the CodeSystem for ICF is http://id.who.int/icd/release/11/icf
FHIR support contains only the latest version of the classification 2025-01 but includes all languages supported in that version see the list
Multilingual Support
The ICD-11 MMS and the Foundation are available in multiple languages. The language can be specified in the request. The language is specified using the displayLanguage parameter. The language is specified using the ISO 639-1 code. In addition to the displayLanguage parameter, the Accept-Language http header can also be used to specify the language.
Valueset expand and CodeSystem lookup support the displayLanguage parameter and Accept-Language header.
Translation extension is used to provide the name and description of the Code Systems in multiple languages when requested using <baseurl>/fhir/CodeSystem endpoint.
Authentication
ICD-API FHIR endpoints have the same OAUTH 2 authentication as the rest of the ICD-API. For more information see API-Authentication
Samples
Postman Samples
We have more samples than the ones shown below as a Postman collection. If you prefer to use Postman, you can download the Postman collection from here
Sample Endpoints
CodeSystem
| endpoint | explanation |
|---|---|
<baseurl>/fhir/CodeSystem |
lists all CodeSystems hosted. |
<baseurl>/fhir/CodeSystem?url=http://id.who.int/icd/entity |
returns all versions of the Foundation |
<baseurl>/fhir/CodeSystem?url=http://id.who.int/icd/release/11/mms&version=2025-01 |
returns the ICD-11 MMS version 2025-01 |
<baseurl>/fhir/CodeSystem/ICD11-MMS-2025-01 |
returns single CodeSytem by providing Id |
<baseurl>/fhir/CodeSystem?name:contains=ICD |
contains can be used on text fields |
<baseurl>/fhir/CodeSystem/$validate-code?url=http://id.who.int/icd/entity&code=http://id.who.int/icd/entity/257068234 |
validate code for foundation entity. We use foundation URI as the code as that is the official identifier for the entities in the foundation |
<baseurl>/fhir/CodeSystem/$validate-code?url=http://id.who.int/icd/entity&code=http://id.who.int/icd/entity/257068234&version=2025-01 |
same as before but version added |
ICD-11 MMS has several identifiers as listed below. As such, code validation and lookup in FHIR can use any of them.
- ICD-11 code: is the traditional identifier. They are relatively short identifiers such as
1A00. Not all entities in the hierarchy have codes. For example, higher level groupings don't have codes. - Linearization URI: is a URI represents the entity in the linearization. For example,
http://id.who.int/icd/release/11/mms/257068234represents 'Cholera' in MMS. - Linearization Release URI: is a URI represents the entity the linearization in a specific release. For example,
http://id.who.int/icd/release/11/2025-01/mms/257068234represents 'Cholera' in MMS in the2025-01release.
<baseurl>/fhir/CodeSystem/$validate-code?url=http://id.who.int/icd/release/11/mms&code=1A00 |
validate code using the ICD-11 code |
<baseurl>/fhir/CodeSystem/$validate-code?url=http://id.who.int/icd/release/11/mms&version=2025-01&code=http://id.who.int/icd/release/11/mms/169328648 |
validate code using the version and linearization URI |
<baseurl>/fhir/CodeSystem/$lookup?system=http://id.who.int/icd/release/11/mms&code=1A00&version=2025-01 |
lookup with version and code |
<baseurl>/fhir/CodeSystem/$lookup?system=http://id.who.int/icd/release/11/mms&code=1A00&version=2025-01&displayLanguage=es |
lookup could specify a language for display |
If the version is not specified, the latest version is used in the response.
As a response to lookup call, the API returns the Parameters resource in which the components of the information on the ICD-11 category are represented as designations or properties.
Here we provide title, synonyms, description and other information as explained in the ICD API schema document (https://id.who.int/icd/schema).
The postcoordination scales that are linked to the entities are provided as references to valuesets.
ValueSet
The postcoordination scales are implemented as valuesets
<baseurl>/fhir/ValueSet?url=http://id.who.int/icd/release/11/2025-01/mms/257068234/postcoordinationScale/infectiousAgent |
ValueSet by URL |
<baseurl>/fhir/ValueSet/$validate-code?url=http://id.who.int/icd/release/11/2025-01/mms/257068234/postcoordinationScale/infectiousAgent&system=http://id.who.int/icd/release/11/mms&code=XN62R |
Validate value set with url, system and code |
<baseurl>/fhir/ValueSet/$expand?url=http://id.who.int/icd/release/11/2025-01/mms/257068234/postcoordinationScale/infectiousAgent |
ValueSet expand |