Oppslagstjenesten REST

Introduksjon

Oppslagstjenesten gir offentlig forvaltning tilgang til innbyggers registrerte kontaktinformasjon. Tjenesten kan benyttes av offentlige virksomheter og virksomheter som utfører tjenester på vegne av det offentlige.

Kontaktregisterets oppslagstjeneste tilbys gjennom et OAuth2 beskyttet REST-API, sikret med Maskinporten. Dette gjør det enkelt å implementere integrasjoner mot registeret.

Bruk av Oauth2

Tilgangskontrollen til api’et benytter seg av Maskinporten sin funksjonalitet for maskin-til-maskin API-autorisasjon

I testmiljøet støtter oppslagstjenesten token fra test.maskinporten.no

Tilgjenglige scopes

API-responsen er avhengig av hvilke scope som er forespurt i tokenet. Tilgjengelige scopes er:

Det vil alltid returneres reservasjonsstatus for brukeren.

Merk at scopene med krr:-prefix er noe konsolidert i forhold til tidligere.

Oppslag på vegne av annen virksomhet

En leverandør kan gjøre oppslag i KRR på vegne av en kunde gjennom delegering av tilgang i Altinn. Med kunde menes virksomheten som har tilgang til KRR, og som leverandøren gjør oppslag for. Kunden gir selv leverandøren fullmakt, og kan når som helst trekke den tilbake.

Slik fungerer det

1. Kunden får tilgang til delegeringsscopene i Maskinporten ved at kunde eller leverandør tar kontakt med servicedesk@digdir.no.
2. Kunden gir leverandøren fullmakt i Altinn (se delegering i Altinn).
3. Leverandøren registrerer delegeringsscopene på sin egen Maskinporten-klient.
4. Leverandøren henter token fra Maskinporten med delegeringsscopene og consumer_org satt til kundens organisasjonsnummer.
5. Leverandøren gjør oppslag i KRR med tokenet.

Leverandøren trenger ett token per kunde. Se eksempel på JWT-grant ved bruk av delegering.

Scope for Altinn-delegering

Delegering i Altinn

Kunden må gi leverandøren fullmakt til API-et i Altinn.

1. Logg inn i Altinn og velg virksomheten.
2. Gå til Tilgangsstyring og velg Maskinportenadministrasjon.
3. Klikk Legg til leverandør og skriv inn leverandørens organisasjonsnummer.
4. Velg API-et “KRR - Delegere på-vegne-av-rettighet” og klikk Gi fullmakt.

Se også veiledning: Maskinportenadministrasjon

Endepunkt

Oppslagstjenesten sin REST-tjeneste tilbyr følgende endepunkt for søk på 1…1000 personer:

Merk: Man vil oppnå vesentlig bedre ytelse (målt i personer/sekund) ved å slå opp 1000 personer 1 gang kontra 1000 enkelt-oppslag.

header-parametere

Følgende header-parametere må brukes på request:

Body i requesten er en JSON-struktur med et element personidentifikatorer som skal inneholde en liste med inntil 1000 personidentifikatorer.

Eksempel på forespørsel

POST /rest/v1/personer
Content-type: application/json
Authorization: Bearer SWDQ_pVct3HIzsIaC3zHDuMmIqffr4ORr508N3p0Mtg=

{
 "personidentifikatorer" : [ "20914695016" ]
}

Eksempel på respons

{
  "personer":
    [
      {
         "personidentifikator": "20914695016",
         "reservasjon": "NEI",
         "status": "AKTIV",
         "kontaktinformasjon":
         {
            "epostadresse": "NULLstillt@default.digdir.no",
            "epostadresse_oppdatert": "2023-06-29T10:14:52+02",
         }
      }
   ]
}

IP-adresser og brannmurkonfigurasjon

Utgående brannmur må være åpen mot disse adressene:

Produksjon

Test

Swagger

OpenAPI-dokumentasjon.