OKT API prototype

The OKT API provides an overview of what health services a patient receives on the municipal level.
The API is developed and maintained by Norsk Helsenett (NHN).

The data for this API is provided by, and in turn consumed by, each respective municipality's EHR (EPJ) systems.
Information is shared intra-municipally.

Prototype

This is a prototype of the API, and must be considered to be a proof-of-concept only.

Functionality

As of version 0.3.0, synthetic test data is offered through the /okt-events and /okt-status GET endpoints.
POST-ing a valid OktEvent to the /okt-events endpoint will store the test data, given that the pid is a valid synthetic Norwegian national identity number.

Delivered OktEvents will only be accessible by other consumers associated with the same parent organization in HelseID.

In addition there is some synthetic test data available for all consumers, associated with the following pids:

• 22750884907
• 19779998080
• 16758532406

/okt-events

GET

The GET endpoint will get the stored OktEvent for the pid specified via path parameter.

POST

The POST endpoint accepts an OktEvent.
It will do some field validation and reply either with an error message or a ResultMessage along with the corresponding HTTP status code.
Only synthetic pids are accepted. See NHN SyntPop to find or create test persons.
Note that iplosCodeValue is the only required field under the iplosCode node.
The description, code level and parent code fields are enriched with data from the IPLOS code system.

/okt-status

Finally, the GET endpoint on /okt-status will give the current OktStatus for any given pid, which is the number of active services (i.e. not on hold).
0 indicates that we do not possess any information on that pid, or that there are no active services.

Data structure

OktEvent

{
  // a valid Norwegian fødselsnummer:
  "personIdentifier": "26812297073",
  // one or more oktMessages:
  "oktMessages": [
    {
      // set if provision of a service ended; date:
      "endDate": "",
      // IPLOS code and descriptions taken from the IPLOS classification:
      "iplosCode": {
        "iplosCodeDescription": "Matombringing",
        "iplosCodeLevel": "1",
        "iplosCodeValue": "05",
        "iplosParentCode": "0"
      },
      // determines if there is a need for more information in the GUI:
      "needsCaption": true,
      // a more detailed description of the service provided:
      "serviceDescription": "utfyllende beskrivelse av tjenesten",
      // on what municipal level this service is provided, i.e. district, 
      // institution, etc.:
      "serviceLevel": "dps",
      // when provision of a service started; date:
      "startDate": "2020-02-02",
      // set if service is provided on the institutional level; extent of stay
      // at institution:
      "stayType": "dagopphold",
      // set if there is a temporary stop in provision of the service:
      "temporaryCessation": false,
      // set if service provided at home; how many hours per week the service
      // is provided:
      "weeklyExtent": "14 timer"
    }
  ],
}

See also the OpenAPI specification (section "Models"). These are object to change and any feedback from vendors is welcome.

OpenAPI specification

See OKT API proto.

Access

Per NHN security guidelines, access to the API is restricted to Norwegian IP addresses.

Authentication and authorization

This API is secured by HelseID.
We use the OAuth2 DPoP mechanism, see HelseID's docs at Utviklerportalen.

To gain access to the API, you need to use HelseID Selvbetjening.

The relevant scopes are:

• nhn:fj-okt/lesetilgang for read access (GET)
• nhn:fj-okt/skrivetilgang for write access (POST)

Changelog

This prototype will rapidly change but we will try to provide a terse changelog for major milestones.

v0.3.0 - Datastore (2024-06-28)

• This release introduces a persistent data store.

v0.2.0 - HelseID (2024-06-18)

• The endpoints are now secured by HelseID.

v0.1.0 - first release

• The initial release if this prototype/proof-of-concept.

Versioning

We will strive to adhere to the Semantic Versioning 2.0.0 standard.

In short; it uses MAJOR.MINOR.PATCH numbers to indicate significant/breaking changes, backward compatible additions, and bug fixes, respectively.