Recommendations / How-Tos

This page contains recommendations on how to use the IKJ-API. The target is to ensure that key information is represented equally independent of its origin. As IKJ is a part of the new implementation of the VKP service, key differences between IKJ and VKP are highlighted.

We are interested in API users' views on contents in this page, so feel free to share your thoughts.

Synchronizing patients from IKJ

We recommend using the EpisodeOfCare search when synchronizing patient lists, as opposed to the Patient search. While the Patient resource lacks data suitable for filtering, the EpisodeOfCare resource contains such information.

Using EpisodeOfCare search makes it possible to filter on service types and managing organizations. This also corresponds well to VKP's service code mapping feature which is not used in IKJ. The EpisodeOfCare search endpoint also has an option to include the related patients. Example:

GET /v1/EpisodeOfCare?managingOrganization.identifier=https://org.com/code|1.2&type=https://type.com/code|3.4&_include=EpisodeOfCare:patient

An EpisodeOfCare that would match the search might look like this:

{
  "resourceType": "EpisodeOfCare",
  "identifier": [
    {
      "use": "official",
      "system": "https://epj.com/id",
      "value": "42"
    }
  ],
  "status": "active",
  "type": [
    {
      "coding": [
        {
          "system": "https://type.com/code",
          "code": "3.4",
          "display": "Type example"
        }
      ]
    }
  ],
  "patient": {
    "reference": "Patient/1234"
  },
  "managingOrganization": {
    "identifier": {
      "system": "https://org.com/code",
      "value": "1.2"
    },
    "display": "Organization example"
  },
  "period": {
    "start": "2026-10-10"
  }
}

EpisodeOfCare types

The type property values in EpisodeOfCare resources submitted to IKJ are indexed. Using type codings is the recommended way to specify the type of health care service which is represented by the resource. Using the coding makes it possible to distinguish between different official code systems and EHR system vendors' service code. Example type:

[
  {
    "coding": [
      {
        "system": "https://fhir.komsat.nhn.no/system/kpr",
        "code": "27",
        "display": "Elektronisk medisineringsstøtte"
      },
      {
        "system": "https:/some.ehr.com/service-codes",
        "code": "2.7",
        "display": "Medisindispenser SuperMax-2000"
      }
    ]
  }
]

Here, the service type is defined by code 2.7 in the EHR system, corresponding to KPR (i.e. IPLOS) code 27. Both coding elements would be indexed and searchable in IKJ.

We recommend using system value https://fhir.komsat.nhn.no/system/kpr when reporting KPR/ IPLOS codes. For EHR system-specific codes we recommend that the application owner defines and uses its own system value.