1 API'ets formål
- 1.1 Registrere ny personverninnstilling
- 1.2 Oppdatere tidligere satt personverninnstilling
2 Tjenesteoversikt
3 Autorisasjon og aksesstoken
4 SettInnbyggersPersonvernInnstilling
- 4.1 Input-parametre
  - 4.1.1 Eksempelrequests
    - 4.1.1.1 Sette et nytt samtykke
    - 4.1.1.2 Trekke et tidligere gitt samtykke
    - 4.1.1.3 Sette en ny reservasjon
    - 4.1.1.4 Trekke en tidligere satt reservasjon
    - 4.1.1.5 Sette ny tilgangsbegrensning
    - 4.1.1.6 Fjerne tidligere satt tilgangsbegrensning
- 4.2 Responsparametre (ved HTTP 200)
  - 4.2.1 Eksempelresponser
    - 4.2.1.1 Ny innstilling registrert eller innstilling ble endret
    - 4.2.1.2 Ingen endringer på innstillingen
- 4.3 Respons ved feil

API-navn	Registrering av eksternt avgitt personverninnstilling
Funksjonelt område	Personverninnstillinger
API-versjon og dato publisert	V2 Oct 4, 2024
Status	I DRIFT
API-dokumentasjon sist endret	Jun 30, 2026
Teknologi	REST

API'ets formål

API’et kan benyttes av eksterne aktører for å registrere, eller oppdatere status, på en personverninnstilling på vegne av innbygger. 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.

API-klienten må eksplisitt gis rettigheter til å registerere personverninnstillinger for den aktuelle PersonverninnstillingDefinisjon.

Registrere ny personverninnstilling

Diagrammet under beskriver flyten for å registre en personverninnstilling, altså et samtykke, en reservasjon eller en tilgangsbegrensning.

Gliffy Diagram

Oppdatere tidligere satt personverninnstilling

For å oppdatere status på en tidligere registrert personverninnstilling, brukes samme endepunkt som for å registrere en ny innstilling. Det er hvorvidt innstillingen eksisterer fra før som avgjør om det blir en nyopprettelse eller endring, hele request-objektet må spesifiseres uansett.

For tilgangsbegrensninger, kan man i tillegg endre HPR-nummer/organisasjonsnummer. Tabellen under beskriver hvordan status påvirker HPR-nummer/organisasjonsnummer.

	HPR-nummer og organisasjonsnummer

HPR-nummer og organisasjonsnummer

Status aktiv

Kan settes

Status inaktiv

Kan ikke settes

Eksisterende HPR-nummer eller organisasjonsnummer slettes når en tilgangsbegrensning settes til inaktiv

Diagrammet under viser vellykket flyt for endringer på en tidligere satt personverninnstilling. To ulike scenarier regnes som vellykkede og vil gi respons 200:

Oppdatere status eller HPR-nummer/org.nummer på tidligere satt personverninnstilling
Det sendes en request på eksisterende personverninnstilling, men requesten har ingen endringer i parametre fra det som allerede er registrert

Gliffy Diagram

Tjenesteoversikt

TjenesteNavn	Http	Beskrivelse

TjenesteNavn	Http	Beskrivelse
SettInnbyggersPersonvernInnstilling	POST <system url>/personvern/Personverninnstillinger/SettInnbyggersPersonvernInnstilling/v2	Nyregistrerer en innbyggers instans av en bestemt personverninnstilling eller endrer status på en allerede satt innstilling.

Autorisasjon og aksesstoken

HelseId sin autoriseringstjeneste for maskin-til-maskin skal benyttes:

Velg Helsenorge Ekstern API i HelseId sin selvbetjeningsløsning
1. Velg deretter scope “Personverninnstillinger_skriv”
2. 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

SettInnbyggersPersonvernInnstilling

Input-parametre

Merk at innstillingens faste metadata som er satt på definisjonen ikke er med i dette grensesnittet.

Navn	Type	Lovlige verdier	Påkrevd	Kommentar

Navn	Type	Lovlige verdier	Påkrevd	Kommentar
innbyggerFnr	string	fødselsnummer (eller D-nummer) (11 siffer)	Ja	Dette er fødselsnummer (eller D-nummer) til innbygger hvis personverninnstilling skal registreres eller endres
definisjonGuid	string	GUID	Ja	GUID for den personverninnstilling definisjon det gjelder
definisjonNavn	string	Navn på innstillingen	Ja	Beskrivende kortnavn på personverninnstilling definisjonen. (Denne er egentlig overflødig da GUID uansett er unik, vi har likevel valgt å ta denne med.)
partKode	string	Forhåndsavtalt verdi	Ja	Kortnavn som identifisere det aktuelle register/screeningprogram/forskningsprosjekt som eier den aktuelle personverninnstilling. Må være kjent på forhånd av kallende system. (Denne er egentlig overflødig da GUID uansett er unik, vi har likevel valgt å ta denne med.)
typePi	string	Type personverninnstilling	Ja	Kan ha en av følgende verdier: samtykke reservasjon tilgangsbegrensning
aktiv	boolean	Innstillingens nye Status	Ja	Kan ha en av følgende verdier: false Samtykke: Ikke samtykket Reservasjon: Ingen Reservasjon satt Tilgangsbegrensning: Ingen tilgangsbegrensning satt true Samtykke: Har samtykket Reservasjon: Reservasjon satt Tilgangsbegrensning: Tilgangsbegrensning satt.
tidspunkt	String	Tidspunkt for når aktuell verdi for innstillingen ble satt. Frivillig felt. Skal være ISO8601 format på UTC tid. Eks: 2023-12-07T08:05:39Z	Nei	Benyttes dersom registreringen til PVK skjer senere enn innstillingen ble satt i eksternt system.
Avhengig av typePi: saInnbyggerMetadata reInnbyggerMetadata tbInnbyggerMetadata	JSON	Struktur med metadata for aktuell type personverninnstilling Se: API- Hente personverninnstillinger	Nei	(C=Conditional). Er kun med dersom definisjonen er av type tilgangsbegrensning der innbygger selv kan angi parametere eller dersom innstillingen er av type Samtykke elle reservasjon og innbygger har satt egne tidsbegrensninger.
signertBevisMimeType (ny Q2 - 2025)	String	Følgende filtytper støttes: image/bmp image/jpeg image/png application/pdf	Nei	Det innføres støtte for at det eksterne systemet kan laste opp “scannet” kopi av et papirskjema som er signert av innbygger. Dette som “bevis” for at innbygger har satt den aktuelle personverninnstilling. Dette arkiveres i PVK sammen med innbyggers personverninnstilling. Det opplastede dokumentet kan hentes ut igjen av registeret/forskningsprosjektet ved behov, f.eks. ved revisjon.
signertBevisInnhold (ny Q2 - 2025)	String (max 4 MB)	Base64 kodet	Nei	Base64 kodet streng med innholdet. Innholdet må være av type angitt i SignertBevisMimeType.

Eksempelrequests

Sette et nytt samtykke

{
   "innbyggerFnr":"11826397979",
   "definisjonGuid":"3FE2A80A-4200-42E2-817B-DA8A6236708A",
   "definisjonNavn":"Samtykke til oppbevaring av biomateriale",
   "partKode":"NFS",
   "typePi": “samtykke”,
   "aktiv": true,
}

Trekke et tidligere gitt samtykke

{
   "innbyggerFnr":"11826397979",
   "definisjonGuid":"3FE2A80A-4200-42E2-817B-DA8A6236708A",
   "definisjonNavn":"Samtykke til oppbevaring av biomateriale",
   "partKode":"NFS",
   "typePi": “samtykke”,
   "aktiv": false
}

Sette en ny reservasjon

{
   "innbyggerFnr":"11826397979",
   "definisjonGuid":"ecc56090-124b-4405-8137-2a616c683ffc",
   "definisjonNavn":"Reservasjon mot registrering av helseopplysninger",
   "partKode":"PDMR",
   "typePi": “reservasjon”,
   "aktiv": true
}

Trekke en tidligere satt reservasjon

{
   "innbyggerFnr":"11826397979",
   "definisjonGuid":"ecc56090-124b-4405-8137-2a616c683ffc",
   "definisjonNavn":"Reservasjon mot registrering av helseopplysninger",
   "partKode":"PDMR",
   "typePi": “reservasjon”,
   "aktiv": false
}

Sette ny tilgangsbegrensning

Enten registrerere ny instans eller oppdatere eksisterende instans med endret helsepersonell.

Merk! Dette blir den nye innstillingen. Eventuelle tidligere satte HPR-nummer blir “overskrevet”.

{
   "innbyggerFnr":"11826397979",
   "definisjonGuid":"3F7457B8-821C-45A8-AE04-D3E4A0DAC0F0",
   "definisjonNavn":"Begrensning av helsepersonells tilgang til legemiddelliste",
   "partKode":"RF",
   "typePi": “tilgangsbegrensning”,
   "aktiv": true,
    "tbInnbyggerMetadata":
    {
       "detaljertAngivelse": 
       {
          "navngittHelseperson": [
             {
                "nummer": "4128168",
                "navn": "Linda Ingrid Telle"
             },
             {
                "nummer":"1234567",
                "navn":"Per Olsen"
             }
          ]
      }
    }
}

Fjerne tidligere satt tilgangsbegrensning

{
   "innbyggerFnr":"11826397979",
   "definisjonGuid":"3F7457B8-821C-45A8-AE04-D3E4A0DAC0F0",
   "definisjonNavn":"Begrensning av helsepersonells tilgang til legemiddelliste",
   "partKode":"RF",
   "typePi": “tilgangsbegrensning”,
   "aktiv": false
}

Responsparametre (ved HTTP 200)

Navn	Type	Lovlige verdier	Kommentar

Navn

Type

Lovlige verdier

Kommentar

returKode

string

ok

ikkeOk

instansEndret

string

endret

ikkeEndret

Dersom retur er "ikkeEndret" betyr dette at aktuell personverninnstilling for denne innbygger allerede hadde angitt verdi eller at et samtykke som trekkes aldri har vært gitt (dvs. det fantes ingen instans).

Eksempelresponser

Ny innstilling registrert eller innstilling ble endret

{
  “returkode”: “ok”,
  "instansEndret":"endret",
 }

Ingen endringer på innstillingen

{
  “returkode”: “ok”,
  "instansEndret":"ikkeEndret",
 }

Respons ved feil

Alle tjenester i API'ene har følgende logikk for HTTP-respons:

Statuskode når kallet er utført ok: 200
Statuskode ved feil internt på Helsenorge: 500
Statuskode ved feil i request: 400
Statuskode ved manglende tilganger: 403
Statuskode ved feil eller manglende autorisasjon: 401

Ved HTTP-statuskoder som tilsier at det har oppstått en feil returneres også en respons med feilkode og feilmelding.

{
  "Code": "SEC-110000",
  "Message": "Token is expired or invalid"
}

API- Registrere personverninnstilling