Denne siden er ment for å gi en oversikt over de viktigste API-ene som bør eller kan være nyttig å bruke i et søknadssystem.

Variabler brukt på denne siden

Variabel	Beskrivelse

Variabel	Beskrivelse
`{miljø}`	Baseurl til miljøet – se Altinn3 App – Miljø
`{app}`	Appens navn/url-del – se Altinn3 App – URL til tjenester
`{instance.id}`	Id på en bestemt instans. Tilgjengelig i responsen når man oppretter en instans, eller ved å hente aktive instanser.
`{instanceOwner.PartyId}`	Unik identifikator for instanseieren i Altinn – se PartyId

Hurtigreferanse

Metode	Formål	Endepunkt

Metode	Formål	Endepunkt
Instans
GET	Se aktive instanser	`{miljø}/dibk/{app}/instances/{instanceOwner.PartyId}/active`
POST	Opprett instans	`{miljø}/dibk/{app}/instances`
GET	Se instans	`{miljø}/dibk/{app}/instances/{instance.id}`
DELETE	Slett instans	`{miljø}/dibk/{app}/instances/{instance.id}`
Data
POST	Last opp data	`{miljø}/dibk/{app}/instances/{instance.id}/data/{dataType}`
PUT	Oppdater data	`{miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}`
GET	Se data	`{miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}`
DELETE	Slett data	`{miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}`
PUT	Legg til metadata	`{miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}/user-defined-metadata`
GET	Se metadata	`{miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}/user-defined-metadata`
GET	Forhåndsvisning PDF	`{miljø}/dibk/{app}/instances/{instance.id}/pdf/preview`
Validering
GET	Dataelementvalidering	`{miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}/validate`
GET	Instansvalidering	`{miljø}/dibk/{app}/instances/{instance.id}/validate`
Signer og send inn
PUT	Signer og send inn	`{miljø}/dibk/{app}/instances/{instance.id}/process/next` Body {action: sign}

Instanser

En instans er en potensiell innsending av tjenesten. Instanser vil være tilgjengelig for instanseier fra de blir opprettet og helt til de eventuelt blir slettet.

PartyId

Hver bruker har en unik identifikator i altinn - instanceOwner.partyId

Denne kan man finne ved å kalle endepunktet /parties med aktuelt ID-porten token.

GET {miljø}/dibk/{app}/api/v1/parties
Headers: {Authorization: bearer [Exchanged ID-porten]}

PartyId som en del av instansId

GET – Se aktive instanser

Dette endepunktet kan benyttes for å avgjøre om en ny instans av en app skal opprettes eller om det er mer hensiktsmessig å fortsette utfylling av en eksisterende instans.

https://docs.altinn.studio/nb/api/apps/instances/#get-active-instances

GET {miljø}/dibk/{app}/instances/{instanceOwner.PartyId}/active
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

POST – Opprett instans

Hver innsending er en instans av en altinn 3 app.

https://docs.altinn.studio/api/apps/instances/

POST {miljø}/dibk/{app}/instances
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

Body:
{
    "appId": "dibk/{app}",
    "instanceOwner": {
        //"organisationNumber": "{organisationNumber}"
        //"personNumber": "{personNumber}"
    }
}

Multipart Request

Instanser kan og opprettes som multipart request der man laster opp data samtidig som man oppretter instansen

Body:
{
    "appId": "dibk/{app}",
    "instanceOwner": {
        //"organisationNumber": "{organisationNumber}"
        //"personNumber": "{personNumber}"
    }
    "{DataType.Id}": File
    "{DataType.Id}": File 
}

GET – Se instans

Se informasjon om den aktuelle instansen.

GET {miljø}/dibk/{app}/instances/{instance.id}
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

DELETE – Slett instans

https://docs.altinn.studio/nb/api/apps/instances/#delete-instance

Med tanke på sikkerhet bør data ikke lagres lenger enn nødvendig. Vi anbefaler derfor å rydde opp og slette instanser som ikke lenger er i bruk, enten fordi de er fullført eller ikke skal brukes mer. Sletting av instanser kan utføres både av instanseier og tjenesteeier. Dersom DiBK etablerer rutiner for sletting av instanser som tilsynelatende ikke er i bruk, vil dette bli dokumentert på de aktuelle tjenestenes egne sider.

DELETE {miljø}/dibk/{app}/instances/{instance.id}
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

Dataelementer

Hver tjeneste har et sett med tillatte datatyper som kan være konfigurert på ulike måter.

Hvilke datatyper som finnes på den aktuelle appen, og hvordan de er konfigurert, finner man ved å kalle appen sitt API endepunkt:

GET {miljø}/dibk/{app}/applicationMetadata

https://docs.altinn.studio/nb/api/models/app-metadata/#datatype

allowedContributers : [org:dibk]

Dette er satt på datatyper som ikke er ment for sluttbruker å laste opp, men datatyper som dibk bruker for å tilgjengeliggjøre data for sluttbruker å lese.

Eksempel på dette kan være valideringsrapport og signatur.

Når en instans blir validert, enten ved å kalle valideringsendepunktet på appen eller som en del av prosessen ved "process next", vil appen sjekke om innholdet i instansen samsvarer med konfigurasjonen. I tillegg vil enkelte ting sjekkes allerede ved opplasting av dataelementer.

Utvidet filvalidering Enkelte datatyper har "utvidet filvalidering" ved opplasting. De aktuelle datatypene er konfigurert med enabledFileValidators og enabledFileAnalysers. Vi ser for oss å bruke dette på alle datatyper som forventer innhold i henhold til bestemte datamodeller og dermed kjøre en skjemavalidering. Eksempel hovedskjema og underskjema i en søknad. Virus scanning https://docs.altinn.studio/nb/app/development/configuration/filescan/ Enkelte datatyper har virus scanning ved opplasting. De aktuelle datatypene er konfigurert med "enableFileScan": true. Foreløpig gjelder dette alle datatyper. Her kommer det endringer om vi ser det som unødvendig å kjøre for hver fil. Metadata om vedlegg Sluttbruker skal kunne legge på metadata på enkelte vedlegg. Dette er ment å erstatte "vedleggsopplysninger" fra altinn2 løsningen. Metadata vil være av typen "key-value", og key verdien vil bli validert mot et sett med lovlige verdier definert på datatypen - allowedKeysForUserDefinedMetadata. Dersom ingenting er definert er det ikke noe begrensninger, men ftpb har en definert liste over hvilke key verdier som blir sendt med videre. allowedContributers definert på datatypen, vil også her styre om man har lov til å legge på metadata på dataelementet. Se mer om hvordan man legger til metadata her

Hovedskjema og underskjema

Datatyper som er brukt for hovedskjema og underskjema er definert på samme måte som andre vedlegg i dataTypes[]. I applicationMetadata kan man se liste over hvilke datatyper som er underskjema og hvilke som er hovedskjema. Elementene i lista peker på Id'n til datatypen:

GET dibk.apps.tt02.altinn.no/dibk/su-v2/api/v1/applicationmetadata

Respons:
.
.
"mainFormDataType": "SU",
"subFormDataTypes": [ 
    "GjennomfoeringsplanV7", 
    "GjennomfoeringsplanV6",
    "GjenpartNabovarsel",
    "DispensasjonssoeknadDataV1"
  ]

POST – Last opp data

Data-elementer – Altinn

Post {miljø}/dibk/{app}/instances/{instance.id}/data/{dataType}
Headers: {
          Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken],
          Content-Disposition: attachment; filename=data.xml,
          Content-Type: application/xml
         }
Binary File: data.xml

PUT – Oppdater data

PUT {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}
Headers: {
          Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken],
          Content-Disposition: attachment; filename=oppdatert.xml,
          Content-Type: application/xml
         }
Binary File: oppdatert.xml

GET – Se data

GET {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

DELETE – Slett data

DELETE {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

PUT – Legg til metadata om vedlegg

PUT {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}/user-defined-metadata
Headers: {Authorization: bearer [Exchanged ID-porten eller Maskinportentoken]}

Body: 
{
  "userDefinedMetadata": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

GET – Se metadata på vedlegg

Du kan hente kun "User-defined-metadata", men det vil og være synlig på dataelementet om man gjør en GET på instans

GET {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}/user-defined-metadata
Headers: {Authorization: bearer [Exchanged ID-porten eller Maskinportentoken]}

Respons: 
{
  "userDefinedMetadata": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

Validering

https://docs.altinn.studio/nb/api/apps/validation/

Validering skjer som en del av prosessflyten i Altinn-appen, men kan også kalles direkte på instansen eller på dataelementer.

Instansvalidering: Denne valideringen sjekker at instansen samsvarer med konfigurasjonen av datatyper i appen og kjører ekstra valideringer som er lagt til på enkelte datatyper.
Dataelementvalidering: For dataelementer som er av datatypene for hovedskjema og underskjema, har vi koblet på validering fra FtPB valideringstjeneste. Dette betyr at de samme valideringene som er tilgjengelige for pre-validering også blir kjørt her.

Responsen fra Altinn-appen vil være forskjellig fra responsen fra FtPB valideringstjeneste. Derfor lagrer vi responsen fra FtPB valideringstjenesten i en datatype som vi kaller Valideringsrapport, som kan hentes ved behov. Denne rapporten vil også bli sendt videre ved innsending av søknaden.

Vi anser ikke responsen fra Altinn som mangelfull, så det er fullt mulig å bruke denne responsen i stedet.

Pre-validering til FtPB valideringstjenesten er et tilbud som kan benyttes hvis det passer best inn i prosessflyten for det aktuelle søknadssystemet. Den samme pre-valideringen kan utføres ved å kalle appens valideringsendepunkter etter man har opprettet en instans og lastet opp data.

GET – Dataelementvalidering

https://docs.altinn.studio//nb/api/apps/validation/#validate-stored-data

GET {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}/validate
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

Endepunktet returnerer en liste med ValidationIssues, og det vil bli lagret en valideringsrapport på datatypen Valideringsrapport.

Filnavnet vil være Valideringsrapport-{datatype.id}-{dataElement.Id}.xml. Hvis det gjøres flere valideringer på samme dataelement, vil rapporten bli overskrevet.

Ved validering av et nytt dataelement av samme datatype, genereres en ny valideringsrapport.

GET – Instansvalidering

https://docs.altinn.studio//nb/api/apps/validation/#validate-stored-instance

GET {miljø}/dibk/{app}/instances/{instance.id}/validate
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

Endepunktet returnerer en liste med ValidationIssues basert på appen og dens konfigurasjon. I tillegg utføres alle relevante valideringer på alle dataelementer som er konfigurert for validering.

Mapping fra FtPB til Altinn sitt valideringsresultat

ValidationIssue (Altinn)	ValidationReport (FtPB)	Eksempel

ValidationIssue (Altinn)	ValidationReport (FtPB)	Eksempel
Severity	MessageType	Error `1`, Warning `2`
DataElementId		Fra appen: `Guid` på dataelementet som blir validert
Field	XpathField	`Planvarsel/vedlegg/KartDetaljert`
Code	Reference	`11000.1.79.51.12`
Description	Message	`Detaljert kart bør sendes med varselet. Husk å markere kartet med gårds- og bruksnummer eller adresse.`
Source	Settes av altinn, hvilke validator som er brukt.	`Altinn.App.logic.Validator.DataElement.PlanvarselValidator-*`

Signer og send inn

Sluttbruker må signere instansen før den kan gå videre til behandling i ftpb.

Det utføres på følgende måte:

PUT {miljø}/dibk/{app}/instances/{instance.id}/process/next
Headers: {Authorization: bearer [Exchanged ID-porten]}

Body: { "action":"sign" }

PDF

Det blir produsert en PDF av både hovedskjemaet og eventuelle underskjemaer. Brukerne skal kunne hente en forhåndsvisning av PDF-en før signering, samt en signert versjon når søknaden er sent inn og signert av brukeren.

GET – Forhåndsvisning

Forhåndsvisning gir hele byggesøknaden - hovedskjema og underskjema.

GET {miljø}/dibk/{app}/instances/{instance.id}/pdf/preview
Headers: {
          Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]
         }

Det er meldt inn ønske til Altinn om at man skal kunne hente ut forhåndsvisning av et dataelement. Eksempel kun hente ut forhåndsvisning av gjennomføringsplan.

https://github.com/Altinn/app-lib-dotnet/issues/1659

Signert PDF

Den signerte PDF-en blir produsert etter at det er gjort en Altinn-signatur og appen har gått videre til prosessens slutt (process end). PDF-en blir tilgjengelig som dataelement på instansen, med metadata referanse til det opprinnelige XML-dataelementet.

Datatype: ref-data-as-pdf

Hovedskjema

dataType: ref-data-as-pdf
metadata: null
Referanse: PdfForm
"references": [ { "value": "PdfForm", "relation": "GeneratedFrom", "valueType": "Task" }

Underskjema

dataType: ref-data-as-pdf
metadata: subformDataElementId peker på underskjema xml'n
"metadata": [ { "key": "subformComponentId", "value": "subform-GjenpartNabovarselDataV3" }, { "key": "subformDataElementId", "value": "e1b1cb93-ae9e-49ea-9947-c96677cab418" } ],

Opprinnelig XML-dataelement "data": [ { "id": "c40fe57d-796f-4624-90c9-5636ecae97a0", "dataType": "RS", "contentType": "application/xml", "fileScanResult": "NotApplicable", "references": null } ] Generert signert PDF-dataelement "data": [ { "id": "57df2f7c-468e-47c9-9510-eed2fd424550", "dataType": "ref-data-as-pdf", "filename": "Søknad om rammetillatelse.pdf", "contentType": "application/pdf", "references": [ { "value": "PdfForm", "relation": "GeneratedFrom", "valueType": "Task" } ] } ]

Fullført instans

Når en instans er signert og behandlet av ftpb, vil instansen få en completeConfirmations.
Når en instans er satt til complete vil instansen kunne slettes av instanseier.

GET {miljø}/dibk/{app}/instances/{instance.id}
.
.
.
"completeConfirmations": [
    {
        "stakeholderId": "dibk",
        "confirmedOn": "2026-05-28T12:50:55.8926945Z"
    }
],

Altinn App API