Verktøy API
API-navn | Verktoy API |
---|---|
Funksjonelt område | |
API-versjon og dato publisert | Siste versjon av API-et Oct 23, 2024 |
Status | I Drift |
API-dokumentasjon sist endret | Jun 16, 2025 |
Teknologi | REST |
API-ets formål
API-et gjør det mulig å hente ut informasjon om digitale helseverktøy som ligger i Verktøykatalogen samt å kunne sende disse verktøyene til innbygger.
API-et tilbyr tjenester for å:
Invitere en innbygger til å ta i bruk et verktøy, som en forenklet versjon av verktøyoppgave. Dette kan kun gjøres fra verktøyet selv. Når et verktøy sendes til innbygger de få verktøyet tilsendt som en oppgave på Helsenorge med en frist.
Hente ut en liste med verktøy og deres metadata med mulighet for å filtrere på fagområder, målgrupper, språk, om verktøyet er nasjonalt tilgjengelig kan brukes uten å måtte logge inn på Helsenorge eller om det krever at innbygger får det tilsendt fra en behandler før det kan brukes.
Hente ut en liste med verktøy og deres metadata basert på søk på verktøynavn og predefinerte søkeord.
Hente ut alle metadata for ett enkelt verktøy
Hente ut informasjon om hvilke behandlere som har sendt verktøyet til aktuell innbygger. Dette er mulig ved at Helsenorge deler informasjon om behandler som har sendt ut verktøyet med verktøyet etter innlogging og oppstart.
Fordeler med API-et
Tjeneste for å sende verktøy til innbygger gir en enklere prosess for behandler når verktøy skal sendes direkte fra verktøyet selv eller annen ekstern løsning behandler benytter (som alternativ til å bruke Verktøyformidleren). Dette er aktuelt for helseaktører som kun skal sende ut ett spesifikt verktøy og ikke trenger fleksibiliteten til å velge blant verktøyene som ligger i Verktøykatalogen.
Tjenester for å hente ut informasjon om verktøy kan benyttes av eksterne aktører som ønsker å bruke og presentere informasjon om digitale helseverktøy på Helsenorge i sine løsninger. På denne måten kan eksterne aktører vise utvalgt informasjon om verktøy direkte fra Verktøykatalogen fremfor å duplisere og manuelt vedlikeholde informasjon i egen løsning. Informasjonen vi da alltid være oppdatert og synkronisert med de siste endringene i Verktøykatalogen.
Tjeneste for å hente ut informasjon om behandlere som har sendt verktøyet til innbyggere gjør det mulig for verktøyene å følge opp bruken og lage funksjonalitet basert på relasjoner mellom innbygger og behandler. Leverandører kan bruke dette til f.eks å kontrollere påkrevde sertifiseringer og lisenser, følge med på bruk og utbredelse og få innsikt i hvilke type behandlere som benytter verktøyet. Det kan også brukes for å opprette nødvendige koblinger mellom innbyggere og pasienter i verktøyet slik at f.eks verktøy med behandlerdel kan sørge for at behandler kun ser sine egne pasienter i verktøyet.
Hvordan benytte API-et
Type API
REST
Metode og parametere til endepunktet
Sende verktøy til innbygger (ny tjeneste fra august 2025)
Beskrivelse: Sender et bestemt verktøy til innbygger. Innbygger vil varsles på Helsenorge om ny oppgave og må ta et aktivt valg om å ta i bruk verktøyet (se funksjonell beskrivelse av Digitale Verktøy). Verktøyet må være definert i Verktøykatalogen på forhånd, og verktøyets unike ID må være kjent i utsendingsfunksjonen i verktøyet.
HTTP-verb: POST
Tjeneste: verktoy
Sikkerhetsmodell: System til system.
HelseId sin autoriseringstjeneste for maskin-til-maskin skal benyttes:
Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning
Velg deretter scope “verktoysendtilinnbygger”
Når tilgangen er godkjent av Helsenorge, kan aksesstoken hentes ut fra HelseId
Se ytterligere detaljer her: 3. Ekstern applikasjon kaller Helsenorge API i systemkontekst
AksessToken som mottas fra HelseId eller Helsenorge STS skal deretter være med i Authorization header i alle HTTP-requestene. Se: 2. Ekstern innbyggerløsning kaller Helsenorge API i innbyggerkontekst
Request
Request eksempel |
---|
{BaseUrl}/verktoy/system/verktoy/v2 |
Parameternavn | Type | Beskrivelse |
---|---|---|
VerktoyId | guid | Verktøyets unike ID slik det er lagret i Verktøykatalogen |
InnbyggerFnr | string | Innbyggers fødselsnummer (type string). Merk! det vil bli feilrespons dersom innbygger ikke er digitalt aktiv på Helsenorge. |
AvsenderOrgNummer | string | Organisasjonsnummer til avsender av verktøyet. |
AvsenderNavn | string | Navn på avsender slik den vil vises for innbygger på Helsenorge. Avsender står fritt til å angi aktuelt ‘nivå’, enten det er virksomhet, avdeling, klinikk eller en bestemt behandler. |
FristDato | DateTime? | Valgfritt. Frist benyttes for å angi når oppgaven skal utføres. Hvis ikke frist angis settes den to uker frem i tid. Innbygger vil også ha mulighet til å utføre oppgaven i tre måneder etter at fristen har utløpt. MERK! Helsenorge benytter kun angitte datoer i forretningslogikken. (Dvs. eventuell angivelse av time, minutt etc., tas ikke hensyn til) |
Melding | string | Valgfritt. En tekstlig beskrivelse av oppgaven som vises til innbygger. Vises i tillegg til en standardtekst om at innbygger har mottatt en oppgave om å ta i bruk et verktøy i forbindelse med et behandlingsforløp. Maks. 1500 tegn. |
Request eksempel |
---|
JSON: {
"VerktoyId": "40b7e336-0a9b-48f6-bd5b-68c471e7971b",
"InnbyggerFnr": "13766991003",
"AvsenderOrgNummer": "999999999",
"AvsenderNavn": "Helsedirektoratet",
"FristDato": "2025-07-11",
"Melding": "Spesifikk info om å ta i bruk verktøyet."
} |
Respons
Respons eksempel |
---|
PseudoId er pasientens generete pseudo-id på helsenorge for den API-klienten som eier verktøyet. {
"PseudoId": null
} |
Som et alternativ til verktøy-APIets funksjon for å sende ut verktøy fra behandlere til innbyggere er det også mulig å benytte oppgave-APIet. Under er en oversikt over forskjellene og hva som brukes når.
Sende ut verktøy til innbygger med Verktøy-APIet | Sende ut verktøy til innbygger med Oppgave-APIet (verktøystartoppgave) |
---|---|
|
|
Dokumentasjon og mer informasjon: se denne siden | Dokumentasjon og mer info: Verktøystartoppgave |
Sende verktøy til innbygger (gammel tjeneste)
Beskrivelse: Sender et bestemt verktøy til innbygger. Innbygger vil varsles på Helsenorge om ny oppgave og må ta et aktivt valg om å ta i bruk verktøyet (se funksjonell beskrivelse av Digitale Verktøy). Verktøyet må være definert i Verktøykatalogen på forhånd, og verktøyets unike ID må være kjent i utsendelses-funksjonen i Verktøyet.
HTTP-verb: POST
Tjeneste: verktoy
Sikkerhetsmodell: System til system.
HelseId sin autoriseringstjeneste for maskin-til-maskin skal benyttes:
Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning
Velg deretter scope “verktoysendtilinnbygger”
Når tilgangen er godkjent av Helsenorge, kan aksesstoken hentes ut fra HelseId
Se ytterligere detaljer her: 3. Ekstern applikasjon kaller Helsenorge API i systemkontekst
AksessToken som mottas fra HelseId eller Helsenorge STS skal deretter være med i Authorization header i alle HTTP-requestene. Se: 2. Ekstern innbyggerløsning kaller Helsenorge API i innbyggerkontekst
Request
Request eksempel |
---|
{BaseUrl}/verktoy/v1/Verktoy |
Parameternavn | Type | Beskrivelse |
---|---|---|
VerktoyId | guid | Verktøyets unike ID slik det er lagret i Verktøykatalogen |
InnbyggerFnr | string | Innbyggers fødselsnummer (type string). Merk! det vil bli feilrespons dersom innbygger ikke er digital aktiv på Helsenorge. |
BehandlerHpr | string | Dette skal være behandlers HPR-nummer dersom dette er kjent i systemet som benytter API-et. |
BehandlerFnr | string | Kan benyttes dersom behandlers HPR-nummer ikke er kjent i systemet som benytter API-et |
FristDato | DateTime? | Valgfritt. Frist benyttes for å angi når oppgaven skal utføres. Hvis ikke frist angis settes den to uker frem i tid. Innbygger vil også ha mulighet til å utføre oppgaven i tre måneder etter at fristen har utløpt. MERK! Helsenorge benytter kun angitte datoer i forretningslogikken. (Dvs. eventuell angivelse av time, minutt etc., tas ikke hensyn til) |
Melding | string | Valgfritt. En tekstlig beskrivelse av oppgaven som vises til innbygger. Vises i tillegg til en standardtekst om at innbygger har mottatt en oppgave om å ta i bruk et verktøy. Maks. 1500 tegn. |
Request eksempel | |
---|---|
JSON: HPR-nummer kjent i system som benytter API, dato for frist og egen melding er angitt: {
"VerktoyId": "68ce99fd-6243-4ab0-b5bc-3ca81dbd53ba",
"InnbyggerFnr": "0506634187",
"BehandlerHpr": "123467",
"FristDato": "2024-09-11",
"Melding": "Spesifikk info om å ta i bruk verktøyet."
} | JSON: Kun behandlers fødselsnummer er kjent i systemet som benytter API-et: {
"VerktoyId": "68ce99fd-6243-4ab0-b5bc-3ca81dbd53ba",
"InnbyggerFnr": "0506634187",
"BehandlerFnr": "12067231456"
} |
Respons
Respons eksempel |
---|
PseudoId er pasientens generete PseudoId på helsenorge for den API-klient som utfører kallet. {
"PseudoId": ""
} |
Verktøymetadataliste
Beskrivelse: Verktøyliste med mulighet for filtrering av metadata. Eventuelle filtre sendes med request som queryparametre.
Tjenesten støtter paginering, default er 10 verktøy pr. side. Maks antall verktøy pr. side er 50.HTTP-verb: GET
Tjeneste: SelvstendigVerktoy
Sikkerhetsmodell: System til system.
HelseId sin autoriseringstjeneste for maskin-til-maskin skal benyttes:
Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning
Velg deretter scope “verktoykatalog_read”
Når tilgangen er godkjent av Helsenorge, kan aksesstoken hentes ut fra HelseId
Se ytterligere detaljer her: 3. Ekstern applikasjon kaller Helsenorge API i systemkontekst
AksessToken som mottas fra HelseId eller Helsenorge STS skal deretter være med i Authorization header i alle HTTP-requestene. Se: 2. Ekstern innbyggerløsning kaller Helsenorge API i innbyggerkontekst
Request
Request eksempel |
---|
{BaseUrl}/verktoy/v1/SelvstendigVerktoy?Fagomrader=2&Malgrupper=2&Sprak=1&KanLeggesTilAvInnbygger=false&KunAnonymTilgang=true&Siderefereanse=1&AntallVerktoy=20 |
Request parametre:
Parameternavn | Type | Beskrivelse |
---|---|---|
Fagomrader | list<enum> | Fagområde som verktøyet tilhører:
|
Klassifiseringer | list<string> | SNOMED CT-klassifisering for verktøyet. |
Malgrupper | list<enum> | Verktøyets målgrupper:
|
Sprak | list<enum> | Hvilke språk som verktøyet støtter
|
KanLeggesTilAvInnbygger | bool? | Om verktøyet er tilgjengelig for alle, eller om det kun er tilgjengelig hvis innbygger får det tilsendt fra en behandler. |
KunAnonymTilgang | bool? | Om verktøyet er helt åpent (ikke krever innlogging) og er tilgjengelig for alle, |
Sidereferanse | int | I forbindelse med paginering, hvilken side som skal returneres. |
AntallVerktoy | int | Antall verktøy som returneres, maks antall er 50. |
Respons
Respons eksempel |
---|
{
"SelvstendigVerktoyListe": [
{
"VerktoyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"Navn": "string",
"Ingress": "string",
"Beskrivelse": "string",
"OpprettetDato": "2023-04-28T14:05:58.923Z",
"EndretDato": "2023-04-28T14:05:58.923Z",
"VerktoyFormal": {
"VerktoyFormalTypeId": 0,
"VerktoyFormalNavn": "string"
},
"FagligAnsvarlig": "string",
"UtvikletAv": "string",
"Sprak": [
{
"SprakNavn": "string",
"SprakKode": "string"
}
],
"Fagomrader": [
{
"FagomradeType": 0,
"FagomradeNavn": "string"
}
],
"Lenker": [
{
"LenkeType": 1,
"LenkeTypeNavn": "string",
"Url": "string"
}
],
"Sokeord": [
"string"
],
"Malgrupper": [
{
"MalgruppeTypeId": 0,
"MalgruppeNavn": "string"
}
],
"GrafiskeElementer": [
{
"GrafiskElementId": 0,
"GrafiskElementTypeNavn": "string"
}
],
"Innholdstyper": [
{
"InnholdstypeId": 0,
"InnholdstypeNavn": "string"
}
],
"Behandlerinnsyn": "string",
"Klassifiseringer": [
{
"KlassifiseringKode": "string",
"KlassifiseringNavn": "string"
}
],
"KreverForskrivning": true,
"Dataansvarlig": {
"Organisasjonsnummer": 0,
"Organisasjonsnavn": "string"
},
"AntattTid": 0
}
]
} |
Respons-parametere:
Parameternavn | Type | Beskrivelse |
---|---|---|
VerktoyId | guid | Verktøyets unike id |
Navn | string | Verktøyets navn |
Ingress | string | Innledende beskrivelse av verktøyet |
Beskrivelse | string | Beskrivelse av verktøyet |
OpprettetDato | DateTime | Når verktøyet ble opprettet |
EndretDato | DateTime | Når verktøyet sist ble endret |
VerktoyFormalTypeId | int | Enumverdi for verktøyets formål: Verdier: 2, 4, 5 |
VerktoyFormalNavn | string | Navn på verktøyets formål Verdier:
|
FagligAnsvarlig | string | Hvem som har det faglige ansvaret for verktøyet |
UtvikletAv | string | Hvem som har utviklet verkøyet |
SprakKode | string | Hvilke språk verktøyet støtter. Verdier:
|
SprakNavn | string | Språknavn: Verdier:
|
FagomradeType | int | Fagområde verktøyet tilhører Verdier: 1, 2, 3 |
FagomradeNavn | string | Navn på fagområde:
|
LenkeType | enum | Type lenke tilknyttet verktøyet. Returnerer verdi 50 som er den eneste gyldige verdien i denne responsen. |
LenkeTypeNavn | string | Lenketypens navn, returnerer: “Lenke til verktøy“ |
Url | Uri | Lenke til verkøyet |
Sokeord | List<string> | Predefinerte søkeord som beskriver verktøyet |
MalgruppeTypeId | int | Id for verkøyets målgrupper Verdier: 1, 2, 3, 4 |
MalgruppeNavn | string | Målgruppenavn Verdier:
|
GrafiskElementId | int | Id til verkøyets grafiske element |
GrafiskElementTypeNavn | string | Type grafisk element Verdier:
|
InnholdstypeId | int | Id for verktøyets innholdstype Verdier: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 |
InnholdstypeNavn | string | Navn på innholdstype Verdier:
|
Behandlerinnsyn | string | Beskriver verktøyets behandlerinnsyn Verdier:
|
KlassifiseringKode | string | Klassifiseringskode |
KlassifiseringNavn | string | Klassifiseringnavn |
KreverForskrivning | bool | Om verktøyet kun er synlig og tilgjengelig hvis behandler har sendt det til aktuell innbygger |
Organisasjonsnummer | int | Organisasjonsnummer til verktøyets dataansvarlig |
Organisasjonsnavn | string | Organisasjonsnavn til verktøyets dataansvarlig |
AntattTid | int? | Antatt tid det tar å gjennomføre verktøyet (angitt i minutter). |
Verktøymetadata
Beskrivelse: Metadata for ett valgt verktøy angitt med en unik id (guid).
HTTP-verb: GET
Tjeneste: SelvstendigVerktoy
Sikkerhetsmodell: System til system.
HelseId sin autoriseringstjeneste for maskin-til-maskin skal benyttes:
Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning
Velg deretter scope “verktoykatalog_read”
Når tilgangen er godkjent av Helsenorge, kan aksesstoken hentes ut fra HelseId
Se ytterligere detaljer her: 3. Ekstern applikasjon kaller Helsenorge API i systemkontekst
AksessToken som mottas fra HelseId eller Helsenorge STS skal deretter være med i Authorization header i alle HTTP-requestene. Se: 2. Ekstern innbyggerløsning kaller Helsenorge API i innbyggerkontekst
Request
Request eksempel |
---|
{BaseUrl}/verktoy/v1/SelvstendigVerktoy/08ead360-0d65-448c-ba9e-8a08f0921c90 |
Parameternavn | Type | Beskrivelse |
---|---|---|
| guid | Unik id for verktøy |
Respons
Respons eksempel |
---|
{
"Selvstendigverktoy": {
"VerktoyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"Navn": "string",
"Ingress": "string",
"Beskrivelse": "string",
"OpprettetDato": "2023-05-02T13:28:34.819Z",
"EndretDato": "2023-05-02T13:28:34.819Z",
"VerktoyFormal": {
"VerktoyFormalTypeId": 0,
"VerktoyFormalNavn": "string"
},
"FagligAnsvarlig": "string",
"UtvikletAv": "string",
"Sprak": [
{
"SprakNavn": "string",
"SprakKode": "string"
}
],
"Fagomrader": [
{
"FagomradeType": 0,
"FagomradeNavn": "string"
}
],
"Lenker": [
{
"LenkeType": 1,
"LenkeTypeNavn": "string",
"Url": "string"
}
],
"Sokeord": [
"string"
],
"Malgrupper": [
{
"MalgruppeTypeId": 0,
"MalgruppeNavn": "string"
}
],
"GrafiskeElementer": [
{
"GrafiskElementId": 0,
"GrafiskElementTypeNavn": "string"
}
],
"Innholdstyper": [
{
"InnholdstypeId": 0,
"InnholdstypeNavn": "string"
}
],
"Behandlerinnsyn": "string",
"Klassifiseringer": [
{
"KlassifiseringKode": "string",
"KlassifiseringNavn": "string"
}
],
"KreverForskrivning": true,
"Dataansvarlig": {
"Organisasjonsnummer": 0,
"Organisasjonsnavn": "string"
},
"AntattTid": 0
}
} |
Respons-parametere:
Parameternavn | Type | Beskrivelse |
---|---|---|
VerktoyId | guid | Verktøyets unike id |
Navn | string | Verktøyets navn |
Ingress | string | Innledende beskrivelse av verktøyet |
Beskrivelse | string | Beskrivelse av verktøyet |
OpprettetDato | DateTime | Når verktøyet ble opprettet |
EndretDato | DateTime | Når verktøyet sist ble endret |
VerktoyFormalTypeId | int | Enumverdi for verktøyets formål: Verdier: 2, 4, 5 |
VerktoyFormalNavn | string | Navn på verktøyets formål Verdier:
|
FagligAnsvarlig | string | Hvem som har det faglige ansvaret for verktøyet |
UtvikletAv | string | Hvem som har utviklet verkøyet |
SprakKode | string | Hvilke språk verktøyet støtter. Verdier:
|
SprakNavn | string | Språknavn: Verdier:
|
FagomradeType | int | Fagområde verktøyet tilhører Verdier: 1, 2, 3 |
FagomradeNavn | string | Navn på fagområde:
|
LenkeType | enum | Type lenke tilknyttet verktøyet. Returnerer verdi 50 som er den eneste gyldige verdien i denne responsen. |
LenkeTypeNavn | string | Lenketypens navn, returnerer: “Lenke til verktøy“ |
Url | Uri | Lenke til verkøyet |
Sokeord | List<string> | Predefinerte søkeord som beskriver verktøyet |
MalgruppeTypeId | int | Id for verkøyets målgrupper Verdier: 1, 2, 3, 4 |
MalgruppeNavn | string | Målgruppenavn Verdier:
|
GrafiskElementId | int | Id til verkøyets grafiske element |