World Health Organization (WHO) Linearization (classification endpoints) API

openapi: 3.0.1
info:
  title: ICD Foundation Linearization (classification endpoints) API
  description: "\n<p>\nICD-API is a REST API that allows programmatic access to the International Classification of Diseases (ICD).\n</p><p>\nFor most users that require accessing the ICD-11 statistical classification with codes, you need to use the <b>Linearization</b> endpoints with the linearizationId set to <b>mms</b>\n</p><p>\n<b>Foundation</b> endpoints provide information on the Foundation Component of ICD-11. \n</p><p>\n<b>ICD10</b> endpoints serves ICD-10 releases. Please note that functionality on the ICD-10 endpoints are limited. (i.e. the search is not provided)\n</p><p>\nFor more information on the API please see the <a href=\"https://icd.who.int/icdapi\">ICD-API home page </a>\n</p>\n"
  license:
    name: ' ICD-11 Terms of Use and License Agreement '
    url: https://icd.who.int/en/docs/icd11-license.pdf
  version: v2.6.0
security:
- oauth2:
  - icdapi_access
tags:
- name: Linearization (classification endpoints)
paths:
  /icd/release/11/{linearizationname}:
    get:
      tags:
      - Linearization (classification endpoints)
      summary: "This endpoint returns basic information on the linearization (classification) such as ICD MMS together with the list of \r\navailable releases"
      operationId: GetReleasesForLinerization
      parameters:
      - name: linearizationname
        in: path
        description: Short name for the linearization. e.g. use mms for ICD Mortality and Morbidity Statistics
        required: true
        schema:
          type: string
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiVersion'
            application/ld+json:
              schema:
                $ref: '#/components/schemas/MultiVersion'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
  /icd/release/11/{linearizationname}/{id}:
    get:
      tags:
      - Linearization (classification endpoints)
      summary: This endpoint returns lists the URIs of the entity in the available releases
      operationId: GetAvailableReleasesForLinearizationEntity
      parameters:
      - name: linearizationname
        in: path
        description: Short name for the linearization. e.g. mms for ICD Mortality and Morbidity Statistics
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Numeric part at the end of the URI for an entity
        required: true
        schema:
          type: string
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiVersion'
            application/ld+json:
              schema:
                $ref: '#/components/schemas/MultiVersion'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
  /icd/release/11/{linearizationname}/{id}/{residual}:
    get:
      tags:
      - Linearization (classification endpoints)
      summary: This endpoint returns the list of the URIs of the residual entity in the available releases.
      operationId: GetAvailableReleasesForLinearizationResidualEntity
      parameters:
      - name: linearizationname
        in: path
        description: Short name for the linearization. e.g. mms for ICD Mortality and Morbidity Statistics
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Numeric part at the end of the URI for an entity.  For residual categories this number is the same as its parent but the residual categories also have other or unspecified at the end
        required: true
        schema:
          type: string
      - name: residual
        in: path
        description: "For residual categories:\r\n            - this could be 'other' for other specified residual category\r\n            - or 'unspecified' for the unspecified residual category"
        required: true
        schema:
          type: string
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiVersion'
            application/ld+json:
              schema:
                $ref: '#/components/schemas/MultiVersion'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
  /icd/release/11/{releaseId}/{linearizationname}:
    get:
      tags:
      - Linearization (classification endpoints)
      summary: This endpoint returns basic information on the released linearization (such as MMS) together with the chapters in it
      operationId: GetLinearization
      parameters:
      - name: linearizationname
        in: path
        description: Short name for the linearization. e.g. mms for ICD Mortality and Morbidity Statistics
        required: true
        schema:
          type: string
      - name: releaseId
        in: path
        description: 'The id for the release. This is generally formatted like this: 2019-04. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications'
        required: true
        schema:
          type: string
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopLevelLinearization'
            application/ld+json:
              schema:
                $ref: '#/components/schemas/TopLevelLinearization'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
  /icd/release/11/{releaseId}/{linearizationname}/{id}:
    get:
      tags:
      - Linearization (classification endpoints)
      summary: This endpoint return information on a linearization entity
      operationId: GetLinearizationEntity
      parameters:
      - name: linearizationname
        in: path
        description: Short name for the linearization. e.g. mms for ICD Mortality and Morbidity Statistics
        required: true
        schema:
          type: string
      - name: releaseId
        in: path
        description: 'The id for the release. This is generally formatted like this: 2019-04. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications'
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Numeric part at the end of the URI for an entity
        required: true
        schema:
          type: string
      - name: include
        in: query
        description: "Some property values such as ancestor and decendant lists are not provided in the response by default. However, it is possible\r\n            to request them. These properties are ancestor, descendant and diagnosticCriteria. For example, if you set include=ancestor, the returned response will \r\n            include all ancestor entity URIs for the requested entity.\r\n            A comma separated list could be used to request multiple optional property values. e.g: include=ancestor,descendant"
        schema:
          type: string
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinearizationEntity'
            application/ld+json:
              schema:
                $ref: '#/components/schemas/LinearizationEntity'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
  /icd/release/11/{releaseId}/{linearizationname}/{id}/{residual}:
    get:
      tags:
      - Linearization (classification endpoints)
      summary: This endpoint return information on a residual linearization entity
      operationId: GetLinearizationResidualEntity
      parameters:
      - name: linearizationname
        in: path
        description: Short name for the linearization. e.g. mms for ICD Mortality and Morbidity Statistics
        required: true
        schema:
          type: string
      - name: releaseId
        in: path
        description: 'The id for the release. This is generally formatted like this: 2019-04'
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Numeric part at the end of the URI for an entity. For residual categories this number is the same as its parent but the residual categories also have other or unspecified at the end
        required: true
        schema:
          type: string
      - name: residual
        in: path
        description: "For residual categories:\r\n            - this could be 'other' for other specified residual category\r\n            - or 'unspecified' for the unspecified residual category"
        required: true
        schema:
          type: string
      - name: include
        in: query
        description: "Some property values such as ancestor and decendant lists are not provided in the response by default. However, it is possible\r\n            to request them. For example, if you set include=ancestor the returned response will include all ancestor entity URIs for the requested entity.\r\n            A comma separated list could be used to request multiple optional property values. (e.g. include=ancestor,descendant"
        schema:
          type: string
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinearizationEntity'
            application/ld+json:
              schema:
                $ref: '#/components/schemas/LinearizationEntity'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
  /icd/release/11/{releaseId}/{linearizationname}/autocode:
    get:
      tags:
      - Linearization (classification endpoints)
      summary: "Provides the best matching classification classification entity (its code, linearization URI, foundation URI and other related information) for the provided search text. \r\nsee AutoCodingSearchResult schema for information on the response."
      operationId: AutoCode
      parameters:
      - name: linearizationname
        in: path
        description: Short name for the linearization. e.g. mms for ICD Mortality and Morbidity Statistics
        required: true
        schema:
          type: string
      - name: releaseId
        in: path
        description: 'The id for the release. This is generally formatted like this: 2019-04. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications'
        required: true
        schema:
          type: string
      - name: searchText
        in: query
        description: Input text for which the matching entity to be provided.
        schema:
          type: string
      - name: subtreesFilter
        in: query
        description: "Optional parameter. Comma separated list of URIs. If provided, the search will be performed on the entities provided and their descendants. \r\n            When searching mms, by default chapters 26, V and X are not included"
        schema:
          type: string
      - name: matchThreshold
        in: query
        description: score is a value between 0 and 1 that indicates the similarity between the input text and the matched term. matchThreshold the minimum score to be included in the output. The API will use default value if not provided
        schema:
          type: number
          format: double
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoCodingSearchResult'
        '401':
          description: Unauthorized
  /icd/release/11/{releaseId}/{linearizationname}/codeinfo/{code}:
    get:
      tags:
      - Linearization (classification endpoints)
      summary: "This endpoint allows looking up an entity from its code. For postcoordinated code combinations, it provides \r\nmore information on the code combination such as which axes are used and what values do they have"
      operationId: GetCodeInfo
      parameters:
      - name: linearizationname
        in: path
        description: Short name for the linearization. e.g. mms for ICD Mortality and Morbidity Statistics
        required: true
        schema:
          type: string
      - name: releaseId
        in: path
        description: 'The id for the release. This is generally formatted like this: 2021-05. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications'
        required: true
        schema:
          type: string
      - name: code
        in: path
        description: The code or code combination that will be looked up. (The & and / characters need to be URL encoded)
        required: true
        schema:
          type: string
      - name: flexiblemode
        in: query
        description: "Normally, codeInfo returns an error when the provided code combination includes codes that are not in the predefined suggested value sets of the entity.\r\n            If the flexibleMode is set to true, it will return a result even when some of the postcoordination values are not in these defined value sets. In this case, the codes\r\n            whose postcoordination axis cannot be detected ('/' postcoordination) will be placed under otherPostcoordination rubric."
        schema:
          type: boolean
          default: false
      - name: convertToTerminalCodes
        in: query
        description: "by default it is false, if set to true, the codes will be changed to use the terminal codes (leaf nodes in the hierarchy).\r\n            In most cases this is done by changing the code to the unspecified resisual child"
        schema:
          type: boolean
          default: false
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeInfo'
            application/ld+json:
              schema:
                $ref: '#/components/schemas/CodeInfo'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
  /icd/release/11/{releaseId}/{linearizationname}/describe:
    get:
      tags:
      - Linearization (classification endpoints)
      summary: "This endpoint provides information on a given code, uri or combination of them. \r\nFor postcoordinated code combinations, it provides  more information on the code combination such as which axes are \r\nused and what values do they have. If the input is a code string such as 1A00&XN62R than it should be provided at the code paramter.\r\nIf the input is a uri string such as http://id.who.int/icd/... then it should be provided at the uri parameter.\r\nThe uri parameter accepts both foundation or linearization uris.\r\nDuring the process, if the postcoordination combination has an equivalent precoordinated entity, the system will return the information on the precoordinated entity."
      operationId: Describe
      parameters:
      - name: linearizationname
        in: path
        description: Short name for the linearization. e.g. mms for ICD Mortality and Morbidity Statistics
        required: true
        schema:
          type: string
      - name: releaseId
        in: path
        description: 'The id for the release. This is generally formatted like this: 2021-05. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications'
        required: true
        schema:
          type: string
      - name: code
        in: query
        description: The code or code combination that will be looked up. (The & and / characters need to be URL encoded)
        schema:
          type: string
      - name: uri
        in: query
        description: Either foundation or linearization uri or uri combination that will be looked up. (The & and / characters need to be URL encoded)
        schema:
          type: string
      - name: simplify
        in: query
        description: If set to true the postcoordinated code set will be simplified. For example, if GC08&XN6P4 is provided (Urinary tract infection & Escherichia coli), with simplified option, the result will be one code (GC08.0 Urinary tract infection, site not specified, due to Escherichia coli)
        schema:
          type: boolean
          default: false
      - name: flexiblemode
        in: query
        description: "Normally, codeInfo returns an error when the provided code combination includes codes that are not in the predefined suggested value sets of the entity.\r\n            If the flexibleMode is set to true, it will return a result even when some of the postcoordination values are not in these defined value sets. In this case, the codes\r\n            whose postcoordination axis cannot be detected ('/' postcoordination) will be placed under otherPostcoordination rubric."
        schema:
          type: boolean
          default: false
      - name: convertToTerminalCodes
        in: query
        description: "by default it is false, if set to true, the codes and linearization URIs in the respone will be changed to use the terminal codes (leaf nodes in the hierarchy).\r\n            In most cases this is done by changing the code to the unspecified resisual child. This does not affect the foundation URIs provided in the response"
        schema:
          type: boolean
          default: false
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostcoordinationSet'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
  /icd/release/11/{releaseId}/{linearizationname}/lookup:
    get:
      tags:
      - Linearization (classification endpoints)
      summary: This endpoint allows looking up a foundation entity within a linearization and returns where that entity is coded in this linearization.
      description: "<br>If the foundation entity is included in the linearization and has a code then that linearization entity is returned. \r\n            If the foundation entity in included in the linearization but it is a grouping without a code then the system will return the unspecified \r\n            residual category under that grouping. \r\n            \r\n<br>If the entity is not included in the linearization then the system checks where that entity is aggregated to and then\r\n            returns that entity. \r\n            "
      operationId: Lookup
      parameters:
      - name: linearizationname
        in: path
        description: Short name for the linearization. e.g. mms for ICD Mortality and Morbidity Statistics
        required: true
        schema:
          type: string
      - name: releaseId
        in: path
        description: 'The id for the release. This is generally formatted like this: 2019-04. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications'
        required: true
        schema:
          type: string
      - name: foundationUri
        in: query
        description: The uri of the foundation entity that you'd like to map to this linearization
        schema:
          type: string
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of the API"
        required: true
        schema:
          type: string
      - name: Accept-Language
        in: header
        description: "ICD-API is multi-lingual. By changing this header, you may make the API respond in different languages\nLanguages will be available as the translations of ICD-11 completes. \nThe values are language codes such as en, es, zh, etc."
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinearizationEntity'
            application/ld+json:
              schema:
                $ref: '#/components/schemas/LinearizationEntity'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
  /icd/release/11/{releaseId}/{linearizationname}/search:
    get:
      tags:
      - Linearization (classification endpoints)
      summary: "This endpoint is for searching the linearization (such as MMS). The search can be customized using the parameters as described\r\nSearch endpoint accepts both GET and POST requests. If the size of the request is too large, you may need to use POST\r\nas HTTP GET has a size limit of 2K"
      operationId: SearchLinearization
      parameters:
      - name: linearizationname
        in: path
        description: Short name for the linearization. e.g. mms for ICD Mortality and Morbidity Statistics
        required: true
        schema:
          type: string
      - name: releaseId
        in: path
        description: 'The id for the release. This is generally formatted like this: 2019-04. All releases are listed at https://icd.who.int/docs/icd-api/SupportedClassifications'
        required: true
        schema:
          type: string
      - name: q
        in: query
        description: Text to be searched. Having the character % at the end will be regarded as a wild card for that word
        schema:
          type: string
      - name: subtreesFilter
        in: query
        description: Optional parameter. Comma separated list of URIs. If provided, the search will be performed on the entities provided and their descendants
        schema:
          type: string
      - name: subtreeFilterUsesFoundationDescendants
        in: query
        description: "When a subtree filter is used the search looks at the linearization descendants of the entities in the subtreefilter.\r\n            If subtreeFilterUsesFoundationDescendants is set to true, the search looks at the foundation descendants of the entities in the subtreefilter"
        schema:
          type: boolean
          default: false
      - name: includeKeywordResult
        in: query
        description: "Optional parameter. Default false. \r\n            If set to true, the search result will also include keyword list \r\n            - if the last word provided is incomplete, keyword list includes all words that start with the incomplete word (word completion mode)\r\n            - if the last word is complete, the keyword list will provide suggested additional words that could be added to the search query. (word suggestion mode)\r\n            The behavior can be seen in the 1st column of the ICD-11 Coding Tool search results"
        schema:
          type: boolean
          default: false
      - name: chapterFilter
        in: query
        description: "Optional, comma or semicolon separated list of chapter codes eg:01;02;21 When provided, the search will be performed only on these chapters.\r\n            If medicalCodingMode=true, the chapterFilter is set to not include all chapters but chapters 26, V and X"
        schema:
          type: string
      - name: useFlexisearch
        in: query
        description: "Changes the search mode to flexible search.\r\n            - In the regular search mode, the Coding Tool will only give you results that contain all of the words that you've used in your search. It accepts different variants or \r\n            synonyms of the words but essentially it searches for a result that contains all components of your search. Whereas in flexible search mode, the results do not have to \r\n            contain all of the words that are typed. It would still try to find the best matching phrase but there may be words in your search that are not matched at all\r\n            - It is recommended to use flexible search only when regular search does not provide a result"
        schema:
          type: boolean
          default: false
      - name: flatResults
        in: query
        description: "Optional parameter. Default value false. If set to true the search result entities are provided in a nested data structure\r\n            representing the ICD-11 hierarchy. Otherwise they are listed as flat list of matches"
        schema:
          type: boolean
          default: true
      - name: highlightingEnabled
        in: query
        description: "Optional. Default is true, if set to false the search result highlighting is turned off\r\n            and the results don't contain special tags for highlighting where the results are found within the text"
        schema:
          type: boolean
          default: true
      - name: medicalCodingMode
        in: query
        description: "This mode is the default and it should be used when searching the classification for medical coding purposes. \r\n            In this mode, the search gives results only from the entities that have a code. The system will search all index terms of an entity.\r\n            i.e. titles, synonyms, fully specified term, all terms of other entities that are in the foundation and aggregated into this entity\r\n            By default The chapters 26, V and X are not included in the search results"
        schema:
          type: boolean
          default: true
      - name: propertiesToBeSearched
        in: query
        description: "The properties to be included in the search. Used only when medicalCodingMode=false.\r\n            For example, if you'd like to search the definitions, then you need to set medicalCodingMode=false and propertiesToBeSearched=Definition \r\n            The valid values that could be used are: \"Title\", \"FullySpecifiedName\", \"Definition\", \"Exclusion\" and \"IndexTerm\" (if \"IndexTerm\" is used, the search will be performed \r\n            on all Titles, Synonyms and FullySpecifiedNames including the ones that are under shoreline (i.e Entities in the foundation but not in MMS. ) In such cases\r\n            the results will be shown based on where the match is aggregated into in MMS.\r\n            More than one property could be used with \",\" as the separator. In this case the results will include matches from any one of these properties"
        schema:
          type: string
      - name: API-Version
        in: header
        description: "Version of the API. Values are like v1,v2.\n For example, if you provide value v2, the API will respond in the format of the version 2 of th

# --- truncated at 32 KB (96 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/who/refs/heads/main/openapi/who-linearization-classification-endpoints-api-openapi.yml