API Document Intelligence

Met deze module bied je een PDF aan en krijg je de herkende velden terug als JSON. Zie ook Document Intelligence.

Voorwaarden

Om een document aan te kunnen bieden is onderstaand een vereiste:

Organisatie is gekoppeld aan de module Document Intelligence.
De gebruiker/robot die de module gaat gebruiken dient gekoppeld te zijn.
Er dient minimaal één model ingericht te zijn voor je organisatie. Dit doet Nidaros voor je.
Er dient voldoende saldo aanwezig te zijn.
Het aan te leveren bestand mag maximaal 30MB in grootte zijn.
Het document mag maximaal 500 pagina's bevatten.

Info

Je gebruikt in de API-call het model-id dat je van Nidaros hebt gekregen, bijvoorbeeld Koopovereenkomst. Per documenttype is er een eigen model-id.

Ondersteunde bestandstypen

Naast PDF kunnen ook andere bestandstypen aangeboden worden:

Soort	Bestandstypen
Algemeen	`.pdf`, `.txt`, `.tif`, `.tiff`, `.eml`, `.msg`, `.zip`
Tekstdocumenten	`.doc`, `.docx`, `.docm`, `.dot`, `.odt`, `.ott`, `.fodt`, `.rtf`
Spreadsheets	`.xls`, `.xlsx`, `.xlsm`, `.xlt`, `.ods`, `.ots`, `.fods`, `.uos`
Presentaties	`.ppt`, `.pptx`, `.pptm`, `.pot`, `.potm`, `.odp`, `.otp`, `.odg`, `.fodp`, `.uop`
Afbeeldingen	`.jpg`, `.jpeg`, `.jpe`, `.png`, `.gif`, `.bmp`

Info

Welke bestandstypen precies verwerkt kunnen worden hangt af van de provider van je model. Bovenstaande lijst geldt voor modellen bij provider Parble. Twijfel je, neem dan contact met ons op.

Document aanbieden

POST /v2/document-intelligence/models/{modelId}/analyze

Input

De call verwacht multipart/form-data:

Onderdeel	Type	Uitleg
`file`	bestand	Het aan te bieden document. Verplicht, maximaal 30MB.
`async`	query	`false` (standaard) wacht op het resultaat, `true` levert het resultaat later op.
`format`	query	Optioneel uitvoerformaat. Normaal niet nodig; laat leeg voor het standaard formaat.

Info

Het id van de aanvraag staat alleen in de X-Request-Id response header, niet in de body. Lees deze header dus altijd uit als je het resultaat later wil ophalen of feedback wil versturen.

Response bij `async=false`

Je krijgt direct het resultaat terug, met Content-Type: application/json.

{
  "Documents": [
    {
      "FileName": "koopovereenkomst.pdf",
      "TotalPages": 4,
      "NeedsReview": false,
      "Fields": {
        "Koopsom": {
          "Text": "€ 425.000,00",
          "Value": 425000.00,
          "Type": "Currency",
          "Confidence": 98.5,
          "Page": 1,
          "NeedsReview": false
        },
        "Leveringsdatum": {
          "Text": "1 september 2026",
          "Value": "2026-09-01",
          "Type": "Date",
          "Confidence": 95.2,
          "Page": 2,
          "NeedsReview": false
        }
      }
    }
  ]
}

Veld	Uitleg
`Documents`	De uitgelezen documenten. Eén aangeboden bestand kan meerdere documenten bevatten.
`FileName`	De bestandsnaam van het uitgelezen document.
`TotalPages`	Het aantal pagina's van het uitgelezen document.
`NeedsReview`	`true` als het document nagekeken moet worden.
`Fields`	De herkende velden. De namen komen uit het model dat voor je is ingericht.
`Text`	De waarde zoals die letterlijk in het document staat.
`Value`	De genormaliseerde waarde, passend bij `Type`.
`Type`	Het herkende type, zie Veldtypen.
`Confidence`	Hoe zeker het uitlezen van dit veld is, in procenten.
`Page`	De pagina waarop het veld gevonden is.
`NeedsReview`	`true` als het veld nagekeken moet worden.

Info

Page begint bij 0. De eerste pagina van een document is dus 0, niet 1.

Welke velden krijg je terug?

Niet elk veld wordt door elke provider aangeleverd. Weet je niet welke provider bij jouw model hoort, neem dan contact met ons op.

Veld	Parble	Azure
`Text`	Ja	Ja
`Value`	Ja	Ja
`Type`	Ja	Ja
`Confidence`	Ja	Ja
`Page`	Ja	Nee
`NeedsReview`	Ja	Nee
`FileName` (per document)	Ja	Nee
`TotalPages` (per document)	Ja	Nee

Ontbrekende velden worden weggelaten uit de JSON. Ga er dus niet van uit dat een veld altijd aanwezig is.

Info

Bij Parble worden ook tabellen uit het document meegegeven. Die komen terug als losse velden, met een naam in de vorm tabelnaam.rij.kolom.

Response bij `async=true`

Je krijgt een 202 terug zonder body. Het id van de aanvraag staat in de X-Request-Id header. Met dat id haal je het resultaat later op.

Warning

Bewaar de X-Request-Id header. Zonder dat id kun je het resultaat van een asynchrone aanvraag niet meer ophalen.

Resultaat ophalen

GET /v2/document-intelligence/requests/{requestId}

Gebruik het id uit de X-Request-Id header van de aanvraag.

Response	Betekenis
`200`	Het resultaat is klaar. Zelfde opbouw als bij `async=false`.
`204`	De aanvraag wordt nog verwerkt. Probeer het later opnieuw.
`400`	Het uitlezen is mislukt, of het id is onbekend.

Info

Er is geen callback of webhook. Vraag het resultaat periodiek op tot je een 200 krijgt. Voor het ophalen van een resultaat worden geen kosten gerekend.

Correcties terugkoppelen

POST /v2/document-intelligence/requests/{requestId}/feedback

Klopt een uitgelezen waarde niet, dan kun je de juiste waarde terugsturen om de AI te verbeteren.

{
  "Documents": [
    {
      "Fields": {
        "Koopsom": {
          "Text": "€ 425.000,00",
          "Value": 425000.00,
          "Type": "Currency",
          "Page": 2
        }
      }
    }
  ]
}

Bij een geslaagde verzending volgt een 202 zonder body.

Warning

Stuur alle velden van het document mee, niet alleen de velden die je gecorrigeerd hebt. Een veld dat je weglaat wordt gezien als een veld dat niet in het document staat. Neem dus het volledige resultaat over, pas de foute waarden aan, en stuur dat geheel terug.

Info

Vul per veld altijd Text, Value, Type en Page in. Ontbreekt er één, dan wordt de feedback geweigerd met een 400.

Wanneer merk je er effect van?

De AI heeft ongeveer drie correcties van hetzelfde veld nodig voordat je verbetering gaat merken.

Warning

Stuur daarvoor niet drie keer hetzelfde document in. Gebruik verschillende documenten van hetzelfde formaat. Zo leert de AI dat een waarde die in die documenten steeds op dezelfde plek staat, zoals een btw-nummer, ook echt de juiste waarde is.

Warning

Deze mogelijkheid is afhankelijk van de provider van je model. Alleen modellen bij provider Parble ondersteunen feedback. Bij een model van een andere provider volgt een 400 met de melding dat de provider geen feedback ondersteunt. Neem contact met ons op als je niet weet welke provider bij jouw model hoort.

Voorwaarden voor het versturen van feedback:

De aanvraag is afgerond en heeft een resultaat.
Bij het model is een documenttype ingericht. Is dat niet zo, neem dan contact met ons op.
Alleen het eerste document uit Documents wordt verstuurd.

Veldtypen

De mogelijke waarden van Type:

Type	Uitleg
`String`	Tekst
`Long`	Geheel getal
`Double`	Getal met decimalen
`Boolean`	`true` of `false`
`Date`	Datum, genormaliseerd naar `JJJJ-MM-DD`
`Time`	Tijd, genormaliseerd naar `uu:mm:ss`
`Currency`	Bedrag, eventueel met valuta
`List`	Lijst met subvelden van hetzelfde type
`Dictionary`	Benoemde lijst met subvelden van verschillende typen
`SelectionGroup`	Reeks geselecteerde waarden
`PhoneNumber`	Telefoonnummer, genormaliseerd naar `+{landcode}{nummer}`
`Address`	Adres
`CountryRegion`	Land, genormaliseerd naar ISO 3166-1 alpha-3, bijvoorbeeld `NLD`
`SelectionMark`	Is het veld aangevinkt?
`Signature`	Is er een ondertekening aanwezig?

Foutmeldingen

Code	Betekenis
`400`	Ontbrekend of leeg bestand, onbekend model-id, ongeldige bestandsnaam, onvoldoende saldo, of ongeldige feedback.
`401`	Niet ingelogd, of de module is niet gekoppeld aan je organisatie of gebruiker.
`413`	Het bestand is groter dan 30MB.
`415`	De call is niet als `multipart/form-data` verstuurd.

Info

Bij een mislukte aanvraag wordt er niets van je saldo afgeboekt. Er wordt pas afgeboekt nadat het uitlezen gelukt is.

API Document Intelligence

Voorwaarden

Ondersteunde bestandstypen

Document aanbieden

Input

Response bij async=false

Welke velden krijg je terug?

Response bij async=true

Resultaat ophalen

Correcties terugkoppelen

Wanneer merk je er effect van?

Veldtypen

Foutmeldingen

Response bij `async=false`

Response bij `async=true`