API- Hente personverninnstillinger
- 1 API'ets formål
- 1.1 Tjenesteoversikt
- 2 Autorisasjon og aksesstoken
- 3 Felles objekter benyttet i respons fra tjenestene
- 4 SjekkInnbyggersPiStatus
- 4.1 Input parametere
- 4.2 Responsparametre
- 4.3 Eksempler
- 4.3.1 Samtykker
- 4.3.2 Reservasjon
- 4.3.3 Tilgangsbegrensning
- 5 HentInnbyggersPiForPart
- 5.1 Input parametere
- 5.2 Responsparametre
- 5.3 Eksempel
- 6 HentInnbyggereAktivePiForDefinisjon
- 7 HentInnbyggersOpplastedeBevis
- 8 Respons ved feil
API-navn | Hent Informasjon om innbyggers personverninnstillinger |
|---|---|
Funksjonelt område | |
API-versjon og dato publisert | V2 May 2, 2024 |
Status | I DRIFT |
API-dokumentasjon sist endret | Feb 12, 2026 |
Teknologi | REST |
API'ets formål
API’et gir eksterne aktører mulighet til å sjekke hvilke innbyggere som har satt hvilke personverninnstillinger. Hver personverninnstilling er beskrevet gjennom en “personverninnstillingdefinisjon” som identifiseres av en Guid. Hver Personverninnstillingdefinisjon eies av en datansvarlig (Part) som identifiseres gjennom en partKode. For å benytte API’et må man kjenne Personverninnstillingdefinisjonens Guid samt eiers partkode.
Det er streng tilgangstyring for denne informasjonen. Normalt har datanasvarlig sin databehandler (dennes API-klient) tilgang til API’et. I tillegg kan andre API-klienter eksplisitt gis tilgang til å hente ut informasjonen.
Tjenesteoversikt
TjenesteNavn | HttpVerb | Beskrivelse |
|---|---|---|
SjekkInnbyggersPiStatus | POST <system url>/personvern/Personverninnstillinger/SjekkInnbyggersPiStatus/v2 | Returnerer status på en bestemt Personverninnstilling for en gitt innbygger. |
HentInnbyggersPiForPart | POST <system url>/personvern/Personverninnstillinger/HentInnbyggersPiForPart/v2 | Returnerer en liste over personverninnstillinger for en bestemt innbygger som tilhører en bestemt aktør inklusiv innstillingenes status. Merk! Denne returnerer kun status på de Personverninnstillinger der det finnes en instans hos aktuell innbygger og der denne har status "Aktiv", dvs. at den er virksom. Historikk vises derfor ikke. |
HentInnbyggereAktivePiForDefinisjon | GET <system url>/personvern/Personverninnstillinger/HentInnbyggereAktivePiForDefinisjon/v2 | Returnerer en liste med fødselsnummer for alle innbyggere som har en aktiv personverninnstilling for en bestemt Personverninnstillingdefinisjon. Kan benyttes for å:
|
HentInnbyggersOpplastedeBevis (kommer Q3 2025) | POST <system url>/personvern/Personverninnstillinger/HentinnbyggersOpplastedeBevis/v2 | Dersom et register/forskningsprosjekt har innhentet en personverninnstilling utenfor Helsenorge, f.eks. et samtykke på papirskjema, kan dette lastes opp til PVK for å arkiveres der sammen med innbyggers personverninnstilling (via metode kallet: “SettInnbyggersPersonvernInnstilling”). Dette metode kallet kan benyttes av registeret/forskningsprosjektet selv ved behov, f.eks. ved revisjon. |
<system url> : Dette er bas.eurl for ekstern api’ene i de forskjellige testsystemer og i produksjon. Oversikt over disse finnes her: Testmiljøer og endepunkter
Autorisasjon og aksesstoken
HelseId sin autoriseringstjeneste for maskin-til-maskin skal benyttes:
Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning
Velg deretter scope “Personverninnstillinger_les”
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
Felles objekter benyttet i respons fra tjenestene
Personverninnstilling definisjoner kan være utformet slik at de har metadata. Slike metadata har tre formål:
De angir i kodeverk personverninnstillingens generelle virkeområde, slik at dette kan tolkes maskinelt (uten å på forhånd vite hva en bestemt innstilling betyr).
Dersom en personverninnstillingdefinisjon tillater at innbygger selv kan sette en eller flere tidsperioder det innstillingen skal være gjeldende, er innbyggers valg med som metadata
For tilgangsbegrensninger er det alltid med metadata. Noen av disse er valg innbygger selv kan gjøre. (F.eks. blokkere tilgang til navngitt helsepersonell).
Litt mer om “faste-metadata”
I alle responser fra API’ene våre så har vi valgt å inkludere også de metadata som er faste for en personverninnstilling. Man kan si at dette kan virke unødvendig, da det register som har fått definert opp en personverninnstilling på Helsenorge, selv “vet” denne informasjonen. (Dvs. hva det betyr for registeret selv dersom innbygger har satt den aktuelle innstilling).
Hovedargumentet for å inkludere denne informasjonen, er at vi har stadig flere UseCase der også andre enn registeret selv benytter personverninnstillingen i sin egen tilgangsstyring. Det er derfor fornuftig å inkludere slik informasjon. Dette betyr at registeret som selv “eier” en innstilling selv kan velge om de vil ta hensyn til de faste metadataene eller ikke.
I API’et for å registrere innbyggers innstillinger som er mottatt utenfor Helsenorge, er de faste metadata for innstillingen ikke med (da jo Helsnorge uansett kjenner disse).
Metadata for samtykker og reservasjoner
Hovedstruktur
SaMetadata eller ReMetadata (Replikering: samtykkeMetadata eller reservasjonMetadata) | Type | Kommentar |
|---|---|---|
saFasteMetadata eller reFasteMetadata (conditional) | Se under. | Er med kun dersom det er definerte faste metadata på definisjonen. Normalt med i alle nyere definisjoner. |
saInnbyggerMetadata eller reInnbyggerMetdata (conditinal) | Se under | Er kun med dersom definisjonen tillater at innbygger setter tidsbegrensninger og innbygger har satt slike. |
Faste metadata for en definisjon
Dette er metadata som beskriver innstillingens virkeområde/omfang og som gjelder alle innbyggere.
fasteMetadata | Type | Lovlige verdier | Kommentar |
|---|---|---|---|
tidsbegrensning | element (conditional) |
| Kun med hvis det er en fast tidsbegrensning for innstillingens virkeområde. Merk! Eventuelle tidsbegrensning gjelder felles for alle “Omfang” elementer (dersom det er flere av disse). |
tidsbegrensetFra | string | Dato | Fra og med |
tidsbegrensetTil | string | Dato | Til og med |
omfangElementer | Liste |
| Det kan være flere enn et slikt element (eventuelt ingen) |
omfangKode (mandatory) | string (kodeverdi) | Omfanget av samtykke/reservasjon: kodeverk fra Volven 7608. Følgende verdier er aktuelle for Samtykke eller Reservasjon: DT: Digital tilgang OF: Oppføring UO: Utlevering av helseopplysninger IO: Innhenting av helseopplysninger DO: Deltagelse i ordning eller tjeneste
|
|
logiskOmfang (optional) | string | Kan ha en av følgende tre verdier:
|
|
presisering (optional) | string | Fritekstfelt: Bilateralt avtalt mellom Register og NHN | Presisering ift. Omfang, benyttes hvis nødvendig |
Metadata som innbygger kan sette selv
Dette er metadata som innbygger kan settes selv, dersom definisjonen tillater det, og som er individuelle pr. innbygger.
saInnbyggerMetadata eller reInnbyggerMetadata | Type | Lovlige verdier | Kommentar |
|---|---|---|---|
tidsbergensning | element (conditional) |
| Kun med dersom definisjonen har gitt innbygger slik mulighet og innbygger har angitt en eller flere tidsperioder. Merk! Eventuell tidsbegrensning satt av innbygger gjelder for hele definisjonen (dvs. for alle eventuelle “omfang” elementer i den faste delen av definisjonen). |
perioder | liste |
|
|