Nokup

Description

This endpoint supports Nokup codes lookup. It will help API clients to send valid Nokup codes when reporting to the Biovigilance reporting area. All text in the Nokup standard are in Norwegian.

Endpoint

[GET] /api/v1/nokup/lookup/{codes?}

Scope

nhn:melde/biovigilans

Error codes

If an invalid URL parameter is passed to the endpoint, a 400 Bad request is returned. If the passed input code is not found, a 200 OK is returned and the payload data is null.

Biovigilance reporting

In the biovigilance report there are seven top level data fields that are always required.

  • StedForHendelsen
  • Hendelsestype
  • MedvirkendeFaktorer
  • Forebyggbarhet
  • FaktiskKonsekvensForPasient
  • Hyppighet
  • MuligKonsekvensVedGjentakelse

All those field values must have valid Nokup codes. Depending on the selected code(s) for each value, other fields (in lower levels) may also be required.

API usage

In order to lookup Nokup codes, several API requests must be sent. The first request is normally to fetch the top level codes (the seven mentioned above). This is done by passing empty or 0 in the codes URL parameter. All top level codes have a list of options. When selecting one option, this may have new options. It this way the client can traverse the code structure down to a leaf node in the tree structure. When a leaf node is reached, a complete and valid Nokup code has been found. This procedure must be performed for all top level nodes.

Example

Let's look at the top level node Hendelsestype, which have code value 2 and ten options. For example the code 2.10.1.1.1 is a complete code for Hendelsestype. Here are the requests needed to lookup that code:

  • ...nokup/lookup → return 7 top level nodes with options. Select code 2
  • ...nokup/lookup/2 → return 10 options. Select code 10
  • ...nokup/lookup/2.10 → return 3 options. Select code 1
  • ...nokup/lookup/2.10.1 → return 14 options. Select code 1
  • ...nokup/lookup/2.10.1.1 → return 7 options. Select code 1
  • ...nokup/lookup/2.10.1.1.1 → complete code

Even though the last request returns two options, we know that this is a complete code, because the field IsLeafNokupNode is true. The options for complete Nokup codes are called additional information. The selected code values for those fields, must be sent in other data fields in the Biovigilance report. In this example, two options are returned, DefinisjonKode and OppdagetKode. New lookup requests must be sent to the API to fetch the options:

  • ...nokup/lookup/2.10.1.1.1.DefinisjonKode → return 5 options. Select for instance 2
  • ...nokup/lookup/2.10.1.1.1.OppdagetKode → return 6 options. Select for instance 4

After the requests in this example have been sent, we have found three of the required values for the Biovigilance report.

  • Hendelsestype: 2.10.1.1.1
  • DefinisjonKode: 2
  • OppdagetKode: 4

Hendelsestype is the most complex area of the seven top level nodes, with up to five levels plus additional information. The other six nodes have only one or two levels and no additional information. They must also got valid Nokup codes in the same way as described above, to build a complete Biovigilance report.

Note

The Nokup standard was developed to cover all health care adverse incidents. However, as mentioned, in Melde it is only the Biovigilance report area which uses Nokup. Therefore it is only code 2.10.xxx which is relevant for Hendelsestype. 2.1.xxx to 2.9.xxx should not be used.

API response data

The Nokup API returns an array of the following data structures. The sequence of array item corresponds to the sequence of input lookup codes.

  • Code
    Nokup code
  • InputType
    One of four values:
    • SingleChoice: One option only may be selected
    • MultipleChoice: Multiple options may be selected
    • All: All options are required, and has to be assigned a valid Nokup code
    • Text: Text input (empty option list)
  • Mandatory
    If true, this code is required. Selection must be done or text entered
  • MaxLength
    Max length. Relvant to text fields only
  • IsAdditionalInfo
    If true, this code is additional information
  • IsLeafNokupNode
    If true, this code is a complete Nokup code (Nokup leaf node)
  • Options
    List of options for this code

The API supports multiple code lookups in one request. Pass a semicolon separated list in the codes URL parameter to perform multi lookup. Example: ...nokup/lookup/3.1;3.2`. Up to ten codes may be passed.

This API is designed in a way that makes it possible to create an interactive user interface, by looking up code(s) at the next level as the user selects codes in one level.