Fra forespørsel til data, steg for steg

En gjennomgang av hele flyten for et datasett som krever samtykke, med alle HTTP-kallene som inngår, fra autorisasjonsforespørsel til høsting.

Hva denne siden viser

De fleste datasett kan hentes med ett kall (direktehøsting). Datasett som krever samtykke, eller der kilden svarer asynkront, går gjennom en akkreditering: du ber om tilgang, får en akkrediterings-ID, venter på at dataene blir tilgjengelige, og høster dem. Denne siden går gjennom den flyten kall for kall, med datasettet RestanserV2 i tjenesten eBevis som eksempel. Det krever samtykke fra virksomheten det spørres om.

Flyten i korte trekk:

1. Autorisasjonsforespørsel – POST /authorization med hvem som spør, hvem det spørres om og hvilke datasett. Svaret er en akkreditering.
2. Samtykke – data.altinn.no sender en samtykkeforespørsel i Altinn. En representant for subjektet svarer der.
3. Status – GET /evidence/{accreditationId} forteller om hvert datasett er klart til høsting.
4. Høsting – GET /evidence/{accreditationId}/{evidenceCode} returnerer dataene.

Alle URL-er under er relative til https://api.data.altinn.no/v1. I testmiljøet er base-URL-en https://test-api.data.altinn.no/v1, se Testing.

Før du begynner

• En API-nøkkel (subscription key) for produktet eBevis fra utviklerportalen, og en Maskinporten-klient med scopet altinn:dataaltinnno/ebevis. Se Kom i gang med API.
• Alle kall har de samme to headerne:

Authorization: Bearer {maskinporten-token}
Ocp-apim-subscription-key: {subscription-key}

• Slå opp datasettet i datasettoversikten. For RestanserV2 står det at det ikke kan direktehøstes, at det krever samtykke, og at akkrediteringen kan være gyldig i inntil 90 dager.

Steg 1: Autorisasjonsforespørsel

Send én forespørsel som dekker alle datasettene du trenger om dette subjektet. requestor er organisasjonsnummeret til den som spør (må være den samme som Maskinporten-tokenet er utstedt til), subject er virksomheten det spørres om.

POST https://api.data.altinn.no/v1/authorization HTTP/1.1
Authorization: Bearer {maskinporten-token}
Ocp-apim-subscription-key: {subscription-key}
Content-Type: application/json

{
  "requestor": "991825827",
  "subject": "998997801",
  "evidenceRequests": [
    {
      "evidenceCodeName": "RestanserV2",
      "requestConsent": true
    }
  ],
  "consentReference": "Anskaffelse 2026/1234",
  "externalReference": "sak-2026-1234",
  "validTo": "2026-12-15T00:00:00Z",
  "languageCode": "no-nb"
}

Feltene:

Svaret er 200 OK med akkrediteringen i svarkroppen. Location-headeren peker på statusressursen for akkrediteringen, den samme som du spør i steg 3. Ta vare på id; alle senere kall bruker den.

HTTP/1.1 200 OK
Location: https://api.data.altinn.no/v1/evidence/3fa85f64-5717-4562-b3fc-2c963f66afa6
Content-Type: application/json

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "requestor": "991825827",
  "subject": "998997801",
  "subjectParty": {
    "scheme": "iso6523-actorid-upis",
    "id": "0192:998997801",
    "norwegianOrganizationNumber": "998997801"
  },
  "requestorParty": {
    "scheme": "iso6523-actorid-upis",
    "id": "0192:991825827",
    "norwegianOrganizationNumber": "991825827"
  },
  "aggregateStatus": {
    "code": 0,
    "description": ""
  },
  "isDirectHarvest": false,
  "evidenceCodes": [
  {
    "evidenceCodeName": "RestanserV2",
    "description": "Return the arrears for the subject company - new format",
    "isAsynchronous": false,
    "maxValidDays": 90,
    "values": [
      {
        "evidenceValueName": "levert",
        "source": "Skatteetaten",
        "valueType": "dateTime"
      },
      {
        "evidenceValueName": "forespurteOrganisasjon",
        "source": "Skatteetaten",
        "valueType": "string"
      },
      {
        "evidenceValueName": "arbeidsgiveravgiftForfaltOgUbetalt",
        "source": "Skatteetaten",
        "valueType": "amount"
      },
      {
        "evidenceValueName": "forskuddstrekkForfaltOgUbetalt",
        "source": "Skatteetaten",
        "valueType": "amount"
      },
      {
        "evidenceValueName": "forskuddsskattForfaltOgUbetalt",
        "source": "Skatteetaten",
        "valueType": "amount"
      },
      {
        "evidenceValueName": "restskattForfaltOgUbetalt",
        "source": "Skatteetaten",
        "valueType": "amount"
      },
      {
        "evidenceValueName": "gebyrForfaltOgUbetalt",
        "source": "Skatteetaten",
        "valueType": "amount"
      },
      {
        "evidenceValueName": "merverdiavgiftForfaltOgUbetalt",
        "source": "Skatteetaten",
        "valueType": "amount"
      }
    ],
    "authorizationRequirements": [],
    "belongsToServiceContexts": [
      "eBevis",
      "Drosjeloyve"
    ],
    "isPublic": false
  }
  ],
  "skippedEvidenceCodes": {},
  "issued": "2026-09-24T10:15:00.4988224+00:00",
  "lastChanged": "2026-09-24T10:15:00.4988224+00:00",
  "validTo": "2026-12-15T00:00:00+00:00",
  "consentReference": "Anskaffelse 2026/1234",
  "externalReference": "sak-2026-1234",
  "languageCode": "no-nb",
  "serviceContext": "eBevis",
  "altinnConsentUrl": "https://am.ui.altinn.no/consent/request?id=b1c2d3e4-…",
  "altinn3ConsentId": "b1c2d3e4-5f60-4718-9a2b-3c4d5e6f7a8b"
}

Noen ting å merke seg i svaret:

• evidenceCodes inneholder hele definisjonen av hvert datasett du ba om, inkludert feltene som kommer i retur (values), slik de også vises i datasettoversikten. authorizationRequirements er alltid tom i svaret; kravene er allerede kontrollert.
• isAsynchronous er false for RestanserV2: det er samtykkekravet, ikke asynkron levering fra kilden, som gjør at datasettet må gå gjennom en akkreditering.
• altinnConsentUrl er lenken til selve samtykkeforespørselen i Altinn. Den samme lenken sendes til subjektet, men du kan også gi den videre selv, for eksempel i din egen dialog med leverandøren.
• aggregateStatus er 0 (ukjent) rett etter opprettelsen. Den beregnes når du lister akkrediteringer (steg 3); bruk statuskallet for status på enkeltdatasett.

Går det galt, forteller feilkoden i svaret hva som var feil: 400 for feil i selve forespørselen, for eksempel ugyldig requestor (1001), ukjent datasett (1007) eller feil i parametere (1017); 401 for manglende eller ugyldig token (1023, 1024); 403 med feilkode 1019 når et tilgangskrav for et datasett ikke er oppfylt. Alle slike brudd samles under den ene koden, enten det er manglende Maskinporten-scope, at requestor ikke er organisasjonen tokenet er utstedt til, eller at requestConsent eller consentReference mangler for et datasett med samtykkekrav; meldingen i svaret sier hvilket krav som feilet. Se feilhåndtering.

Steg 2: Samtykke i Altinn

Når akkrediteringen er opprettet, sender data.altinn.no en samtykkeforespørsel til subjektet i Altinn. En representant med riktig rolle får melding i Altinn-innboksen og varsel på e-post og SMS, og godtar eller avslår der. Hvordan det ser ut for den som samtykker er vist under Samtykke og fullmakt; hvilke roller som kreves står under Rollekrav i Altinn.

Du trenger ikke gjøre noe i dette steget, men du kan sende en purring hvis svaret drøyer:

POST https://api.data.altinn.no/v1/accreditations/3fa85f64-5717-4562-b3fc-2c963f66afa6/reminders HTTP/1.1

GET på samme URL viser hvilke purringer som er sendt tidligere. Purringer er begrenset: det går ikke å purre igjen før det er gått sju dager siden forrige vellykkede purring, eller ett døgn etter et mislykket forsøk. Forsøk innenfor sperretiden avvises med 403 og feilkode 1019.

Steg 3: Sjekk status

Spør om status for alle datasettene i akkrediteringen:

GET https://api.data.altinn.no/v1/evidence/3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTP/1.1

[
  {
    "evidenceCodeName": "RestanserV2",
    "status": {
      "code": 2,
      "description": "Awaiting consent from subject entity representative"
    },
    "validFrom": "2026-09-24T10:15:00+00:00",
    "validTo": "2026-12-15T00:00:00+00:00"
  }
]

Statuskodene er faste innenfor API-versjonen. Kode 1–5 er de som er listet i metadata-API-et; 6 og 7 kan du møte for datasett som leveres asynkront fra kilden og for datasett som er tatt ut av drift:

Det finnes ingen varsling når status endrer seg; du må spørre. Et samtykke gis av en person som først skal lese meldingen i Altinn, så regn med at det tar timer eller dager, ikke minutter. Ikke spør på hver enkelt akkreditering med korte mellomrom. Hent i stedet alle akkrediteringer som er blitt klare i ett kall, én eller to ganger i døgnet, og bruk changedafter til å be om bare det som har endret seg siden sist:

GET https://api.data.altinn.no/v1/accreditations/?onlyavailable=true&changedafter=2026-09-24T00:00:00Z HTTP/1.1

Trenger noen svar raskere, er en purring (steg 2) til den som skal samtykke et bedre virkemiddel enn hyppigere spørringer.

Steg 4: Høst dataene

Når status er 1, hentes datasettet slik:

GET https://api.data.altinn.no/v1/evidence/3fa85f64-5717-4562-b3fc-2c963f66afa6/RestanserV2 HTTP/1.1

{
  "evidenceStatus": {
    "evidenceCodeName": "RestanserV2",
    "status": { "code": 1, "description": "The information is available for harvest" },
    "validFrom": "2026-09-24T10:15:00+00:00",
    "validTo": "2026-12-15T00:00:00+00:00"
  },
  "evidenceValues": [
    { "evidenceValueName": "levert", "source": "Skatteetaten", "timestamp": "2026-09-24T11:02:10Z", "value": "2026-09-24T11:02:09Z", "valueType": "dateTime" },
    { "evidenceValueName": "forespurteOrganisasjon", "source": "Skatteetaten", "timestamp": "2026-09-24T11:02:10Z", "value": "998997801", "valueType": "string" },
    { "evidenceValueName": "arbeidsgiveravgiftForfaltOgUbetalt", "source": "Skatteetaten", "timestamp": "2026-09-24T11:02:10Z", "value": "0 NOK", "valueType": "amount" },
    { "evidenceValueName": "merverdiavgiftForfaltOgUbetalt", "source": "Skatteetaten", "timestamp": "2026-09-24T11:02:10Z", "value": "12500 NOK", "valueType": "amount" }
  ]
}

Dataene ligger i evidenceValues, ett element per felt i datasettet, med feltnavn og type slik de er beskrevet i datasettoversikten. valueType beskriver hva verdien betyr, ikke nødvendigvis JSON-typen: verdier av typen amount (og string, uri) serialiseres alltid som tekst, og RestanserV2 legger dessuten på valuta, for eksempel "12500 NOK". Felt som ikke har fått noen verdi kommer uten value. Konvolutten rundt kan fjernes med ?envelope=false, og svaret kan filtreres med et JMESPath-uttrykk i query; se konvolutt og filtrering.

Du kan høste samme datasett flere ganger så lenge akkrediteringen er gyldig og samtykket ikke er trukket. Merk forskjellen mellom de to kallene: statuskallet i steg 3 bygger på det data.altinn.no har registrert om samtykket, mens høstingskallet kontrollerer samtykket live mot Altinn hver gang. Et samtykke som trekkes tilbake i Altinn kan derfor fortsatt vises som status 1 helt til du prøver å høste; da svarer høsting med 403 og feilkode 1010. Det samme svaret får du så lenge samtykket venter (status 2) eller er utløpt (status 4). Bruk statuskallet til å finne ut hva som er verdt å hente, og høstingskallet som den endelige kontrollen.

Livssyklus og opprydding

• Akkrediteringen gjelder til validTo, begrenset av datasettets maksimale gyldighet (90 dager for RestanserV2). Etter det kan du ikke lenger hente data på den.
• Trenger du dataene igjen etter utløp, sender du en ny autorisasjonsforespørsel; det utløser en ny samtykkeforespørsel.
• En akkreditering du er ferdig med kan slettes:

DELETE https://api.data.altinn.no/v1/accreditations/3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTP/1.1

Feilhåndtering

Feil returneres med en feilkode og en beskrivelse i svaret. Kodene endres ikke innenfor en API-versjon, så du kan trygt reagere på dem i kode. De du oftest møter i denne flyten:

Den fullstendige listen finnes i det åpne metadata-API-et: feilkoder og statuskoder. 503 betyr ikke alltid at en kilde er nede, så sjekk feilkoden før du velger strategi: 1016 betyr at et asynkront datasett fortsatt venter, og svaret oppgir når du tidligst bør prøve igjen; 1013 og 3001 betyr at tjenesten eller kilden er midlertidig utilgjengelig.

Snarvei: direktehøsting

Datasett som ikke krever samtykke og der kilden svarer synkront, trenger ingen akkreditering. Ett kall gir dataene:

GET https://api.data.altinn.no/v1/directharvest/UnitBasicInformation?subject=998997801&envelope=false HTTP/1.1

Datasettoversikten viser for hvert datasett om det kan direktehøstes, og gir ferdige eksempler både for HTTP og for DAN SDK, som pakker inn hele flyten på denne siden i noen få metodekall for .NET.