Codingsystems API

This service reads coding systems from various sources. It keeps the codes in a common data model so that other services can retrieve them easily.

Since the coding systems does not change very often this service is intended to be called normally once pr. day, so your system can cache the coding systems internally for faster search.

The purpose of the coding systems present in this service is to provide codes used in the Critical-Information and Patient-Info services.

Clients are free to use this service as a convenience instead of downloading the coding systems from each source themselves.

NOTE: This service is currently only available in the test environment. It will be available in production within Q1 2026. Be aware that minor changes might be made to the API in this period.

Intro coding systems

Coding systems are groups of codes used to document clinical information in an electronic patient journal (EPJ). For example diagnoses, test results, medications, etc.

Coding systems sources

The source for FEST and ATC codes can be found at DMP (see "Rekvirent-uttrekk").

FEST* codes are read once a day (04.00 UTC time) against DMP, which usually issues updates two times a month. ATC codes are partially updated via the FEST* codes once day (when new ATC relations are added), and also manually read once a year for deactivated codes and new codes which are not relations.

Kjernejournal FinnKode codes can be found on FinnKode. ICD-10 codes can also be found at FinnKode. FinnKode codes are read once a day (04.00 UTC time).

Snomed CT (SCT) is one of the largest international coding systems, but not in use in this service (SCT browser).

For each coding system the source is specified in CodingSystemType in the data model below.

Custom changes

Please note that since this service is intended to primarily support the Critical-Information service, we have made some minor changes to some of the coding systems. These changes include:

• Deactivated codes which are inactive ingredients (salts) for "Terapeutiske Virkestoff" codes in the FEST_VIRKESTOFF coding system since they should not be used in the Critical-Information service.
• Custom description for FEST codes based on SUPERKORTFORM + Varenavn (drug trade name), if they are present, to make search easier.
• Added a custom field Code.searchWords to make search easier (see data model below). Might be empty for some of the codes and coding systems.
• Added extra metadata for some of the codes like e.g. SOKEORD and VARSLING_OVER_65.

API Headers

The API can be accessed without authorization. Expected headers are described below.

API Endpoints

There're only two endpoints in the API. See more details below.

GET https://test.codingsystems.hit.nhn.no/api/codingsystems/v1/types

GET https://test.codingsystems.hit.nhn.no/api/codingsystems/v1/codes/{CodingSystemType}

When getting coding systems it's recommended that you first do one request to get all the available coding system types. Then get the codes in parallel for each coding system type.

Documentation for error handling can be found here. Available environments can be found here.

Coding system types

To get all available types of coding systems use the following url:

GET https://test.codingsystems.hit.nhn.no/api/codingsystems/v1/types

The endpoint returns a List<CodingSystemType> serialized as JSON (see data model below).

Example response:

[
  "ATC",
  "FEST",
  "FEST_VIRKESTOFF",
  "FEST_VIRKESTOFF_MED_STYRKE",
  "ICD10",
  "SUPERKORTFORM",
  "KJ_KRIT_MED_TILSTAND",
  "KJ_PF_SYKDOM",
  "KJ_PF_SYK_KATEGORI",
  "KJ_KOMMUNIKASJON",
  "KJ_ANDRE_PROSEDYREENDRINGER",
  "KJ_INTUBASJON"
]

Codes

To get all codes for a single coding system type, e.g. KJ_INTUBASJON, use the following url:

GET https://test.codingsystems.hit.nhn.no/api/codingsystems/v1/codes/KJ_INTUBASJON

Note that some of the coding systems, e.g. FEST*, ICD10 and ATC, can get quite large (tens of megabyte). For faster download you can use the HTTP header Accept-Encoding=gzip to compress the response if your HTTP client supports it.

The endpoint returns a Map<String, Code> serialized as JSON (see Code in the data model below). The Map key (always uppercase) equals to Code.code in the Map value. This is useful for fast search on a code in large coding systems.

Example response:

{
  "1": {
    "code": "1",
    "codingSystem": "KJ_INTUBASJON",
    "description": "Grad 1: Hele stemmespalten synlig",
    "relationsTo": [],
    "metadata": [],
    "searchWords": [],
    "deactivatedTime": null
  },
  "2": {
    "code": "2",
    "codingSystem": "KJ_INTUBASJON",
    "description": "Grad 2: Bakre del av introitus kan sees/ epiglottis og aryregionen synlig",
    "relationsTo": [],
    "metadata": [],
    "searchWords": [],
    "deactivatedTime": "2021-12-09T22:59:00Z"
  }
}

Response data model

For a single code in the HTTP response body (above) the API returns the data model below. The data model is represented in fully functional Java code and is fully documented. You can copy the code and e.g. use an AI agent to translate it to your specific programming language.

A Code is part of a CodingSystemType.

A Code can have multiple relations to other codes (CodeRelation). Relations are used when codes are clinically relevant to each other. Related codes might be deactivated.

A code or a relation can have multiple Metadata. Metadata is used to add additional information to the code or relation.

/// Represents a single code in a coding system.
record Code(
        // The value of the code. Always uppercase.
        String code,
        
        // The type of coding system this code belongs to.
        CodingSystemType codingSystem,

        // Textual description of the code.
        String description,

        // The codes this code is related to (if any).
        Set<CodeRelation> relationsTo,
        
        // Additional information for this code (if any).
        Set<Metadata> metadata,

        // Useful when searching for this code.
        // Contains words from description, metadata and relations of this code (if any).
        Set<String> searchWords,
        
        // If not null, the time this code was deactivated.
        // Serialized with ISO time formatting (always UTC), e.g. "2021-12-09T22:59:00Z".
        @Nullable Instant deactivatedTime
) {}

/// Represents a related code.
/// Relations are used when codes are clinically relevant to each other.
record CodeRelation(
        // The related code value. Always uppercase.
        String code,
        
        // The type of coding system the related code belongs to.
        CodingSystemType codingSystem,

        // Textual description of the related code.
        String description,
        
        // The type/meaning of the relation.
        RelationType relationType,
        
        // Additional information for this relation (if any).
        Set<Metadata> metadata,

        // If not null, the time the related code was deactivated.
        // Serialized with ISO time formatting (always UTC), e.g. "2021-12-09T22:59:00Z".
        @Nullable Instant deactivatedTime
) {}

/// Represents metadata for a code or a relation.
/// Metadata is used to add additional information to a code or a relation.
record Metadata(
        // The type/meaning of the metadata.
        MetadataType metadataType,
        
        // The value of the metadata.
        String metadata
) {}

/// Represents the type/name of a coding system.
/// We do _NOT_ guarantee backwards compatibility for the types since many come from external sources.
/// We will update this list if changes occurs and make a notification in the Critical-Information Slack channel.
enum CodingSystemType {
    // Coding systems where this service is master (NHN).
    KJ_KRIT_MED_TILSTAND, // Also refered to as "Absoluttlisten".
    KJ_PF_SYKDOM, // Used in the Patient-Info service.
    KJ_PF_SYK_KATEGORI, // Used in the Patient-Info service.

    // Coding systems from DMP (Direktoratet for Medisinske Produkter).
    ATC,
    FEST,
    FEST_VIRKESTOFF,
    FEST_VIRKESTOFF_MED_STYRKE,
    SUPERKORTFORM,

    // Coding systems from FinnKode.
    ICD10, // FinnKode ID 7110
    KJ_KOMMUNIKASJON, // FinnKode ID 7525, used in the Patient-Info service.
    KJ_ANDRE_PROSEDYREENDRINGER, // FinnKode ID 7522 
    KJ_ANNEN_ALLERGI, // FinnKode ID 7514
    KJ_BEHANDLING, // FinnKode ID 7517
    KJ_IMPLANTAT, // FinnKode ID 7518
    KJ_INTUBASJON, // FinnKode ID 7515
    KJ_KMT_BEGRUNNELSE, // FinnKode ID 7513
    KJ_MASKEVENTILASJON, // FinnKode ID 7516
    KJ_SMITTETYPE, // FinnKode ID 7519
    KJ_ALVORLIGHETSGRAD, // FinnKode ID 7520
    KJ_KILDE_OPPLYSNINGER, // FinnKode ID 7498
    KJ_SANNSYNLIGHET, // FinnKode ID 7521
    KJ_KRITISK_INFO_UNDERKATEGORI, // FinnKode ID 7651
    KJ_REAKSJONS_TYPE // FinnKode ID 7497
}

/// Represents the type/meaning of a relation between codes, i.e. the reason for why the relation exists.
/// We do _NOT_ guarantee backwards compatibility for the types since many come from external sources.
/// We will update this list if changes occurs and make a notification in the Critical-Information Slack channel.
enum RelationType {
    /// Whether a FEST code is related to a ATC code.
    HAR_ATC_KODE,
    
    /// Whether a FEST code has a relation containing a short form description of the code.
    HAR_SUPERKORTFORM,

    /// Whether a FEST code is related to a FEST_VIRKESTOFF_MED_STYRKE code.
    INNEHOLDER_VIRKESTOFF,

    /// Whether a FEST code is related to a FEST_VIRKESTOFF_MED_STYRKE code.
    INNEHOLDER_VIRKESTOFF_MED_STYRKE,
    
    /// Whether a FEST_VIRKESTOFF_MED_STYRKE code is related to a FEST_VIRKESTOFF code.
    HAR_VIRKESTOFF,

    /// Whether a FEST_VIRKESTOFF code (salt) contains a relation to a code containing the therapeutic active ingredient.
    HAR_TERAPEUTISK_VIRKESTOFF,

    /// Whether a KJ_PF_SYKDOM code is related to a KJ_PF_SYK_KATEGORI code.
    TILHORER_PF_SYK_KATEGORI,

    /// Whether a KJ_KRIT_MED_TILSTAND code can be mapped to one or more ICD10 codes.
    OMFATTER_ICD10_KODE,

    /// Whether a KJ_KRIT_MED_TILSTAND code contains a relation to a code with addition information about clinical consequences.
    KLINISK_KONSEKVENS,

    /// Whether a code is replaced by another code. In use for ATC codes.
    ERSTATTET_AV
}

/// Represents the type/meaning of metadata for a code or a relation, i.e. the reason for why the metadata exists.
/// We do _NOT_ guarantee backwards compatibility for the types since many come from external sources.
/// We will update this list if changes occurs and make a notification in the Critical-Information Slack channel.
enum MetadataType {
    /// The trade name for a FEST code.
    VARENAVN,
    
    /// A manually added search word for a code. Added to Code.searchWords.
    /// Valid for coding systems ICD10, KJ_PF_SYKDOM, ATC, FEST_VIRKESTOFF, FEST and KJ_KRIT_MED_TILSTAND.
    SOKEORD,
    
    /// Additional clinical information for a KJ_KRIT_MED_TILSTAND.
    /// For codes from FinnKode, e.g. KJ_SMITTETYPE, metadata of this type contains the FinnKode 'Forklaring' field.
    HJELPETEKST,

    /// Whether a KJ_PF_SYKDOM code should be considered registered as Critical-Information.
    POTENSIELL_KI,
    
    /// Relevant URL for a KJ_KRIT_MED_TILSTAND code.
    URL,
    
    /// Information that health care professionals should be alerted to for a ATC code.
    VARSLINGSNAVN,

    /// Clinical consequences about a ATC code which should be alerted to health care professionals for all patients.
    VARSLING_ALLE,
    
    /// Clinical consequences about a ATC code which should be alerted to health care professionals for patients over 65 years old.
    VARSLING_OVER_65,
    
    /// Other measures that health care professionals should be alerted to for a ATC code.
    VARSLING_TILTAK,
    
    /// Whether a ATC level 2 code can have search words.
    ATC_LEVEL_2_SOK,
    
    /// Consequences about treatment of the patient for a KJ_KRIT_MED_TILSTAND code.
    KONSEKVENS
}