API-documentatie

Stuur een PDF, Word-document of afbeelding en ontvang gestructureerde JSON terug.

Inleiding

U beschrijft de gewenste gegevens als een categorie: een lijst velden zoals factuurnummer, datum of factuurregels, ingesteld in het dashboard. Parsevix leest het document, vult die velden en geeft ze terug als JSON, samen met de gelezen tekst en de plek waar elke waarde is gevonden.

De API wordt via HTTPS aangeboden vanaf één basis-URL. Requests en responses zijn JSON, behalve bestandsuploads, die multipart/form-data zijn.

https://parsevix.com/api/v1

Elke API-sleutel hoort bij één project. Een sleutel ziet en wijzigt alleen de documenten, categorieën en webhooks van dat project.

Naast aanroepen van de API kunt u resultaten ontvangen via webhooks, Zapier koppelen of documenten naar het e-mailadres van een project sturen.

Conventies

API-responses gebruiken veldnamen in camelCase. Bodies van webhooks en callbacks gebruiken snake_case.
Tijdstempels zijn in UTC, in ISO 8601 (2026-10-25T10:12:06.791Z).
Foutmeldingen zijn in het Engels, Duits, Turks, Frans, Spaans, Italiaans, Nederlands, Pools of Portugees, afhankelijk van de header Accept-Language.

Snelstart

1
Maak een API-sleutel aan
Open in het dashboard uw project, ga naar API-sleutels en maak een sleutel aan. Deze wordt één keer getoond; bewaar hem, bijvoorbeeld als omgevingsvariabele PARSEVIX_API_KEY. Het Free-abonnement bevat één sleutel, betaalde abonnementen meer (zie Limieten en credits).
2
Definieer een categorie
Maak onder Categorieën een categorie aan voor uw documenttype en voeg de velden toe die u nodig hebt, of begin met een ingebouwde sjabloon. De voorbeelden op deze pagina gebruiken een categorie met de naam Supplier invoice.
3
Verstuur een document
POST /extract uploadt het bestand en wacht op het resultaat. De response bevat de gevulde velden onder extracted.

Om veel documenten te verwerken zonder requests open te houden, uploadt u asynchroon en ontvangt u de resultaten via webhooks.

curl https://parsevix.com/api/v1/extract \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf \
  -F category="Supplier invoice"

Response200· ingekort

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "specific",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "language": "en",
  "retained": false,
  "extracted": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

Videotutorials

Vijf korte video's laten de belangrijkste stappen in het dashboard en uw eerste API-verzoek zien. Elke video heeft gesproken tekst en ondertitels in negen talen: kies ze onder het tandwielpictogram in de speler.

De video's worden afgespeeld vanaf YouTube (youtube-nocookie.com). Tot u op afspelen klikt, wordt er niets van YouTube geladen; daarna ontvangt Google uw IP-adres en kan het cookies opslaan. Zie ons Privacybeleid.

Authenticatie

Stuur uw API-sleutel bij elke request mee in de header X-API-Key.

X-API-Key: psvx_…

Een sleutel werkt alleen op /api/v1; u kunt zich er niet mee aanmelden bij het dashboard. Sleutels worden in het project onder API-sleutels aangemaakt en ingetrokken. Een ingetrokken sleutel werkt direct niet meer.

Bewaar sleutels op uw server. Iedereen met een sleutel kan documenten uploaden en de resultaten van het project lezen, en die uploads verbruiken uw credits.

Als een sleutel wordt geweigerd

Status	Code	Betekenis
401	`apikey.missing`	Er is geen header `X-API-Key` meegestuurd.
401	`apikey.invalid`	De sleutel bestaat niet of is ingetrokken.
403	`apikey.plan_disabled`	Het abonnement van het account bevat geen API-toegang.
403	`apikey.paused_by_plan`	De sleutel of het bijbehorende project is gepauzeerd, omdat het abonnement van het account minder sleutels of projecten toestaat.
403	`apikey.account_unavailable`	Het account is opgeheven of staat gepland voor verwijdering.
403	`apikey.project_unavailable`	Het project van de sleutel is verwijderd.
429	`apikey.too_many_invalid`	Er kwamen binnen 10 minuten meer dan 30 ongeldige sleutels van uw netwerk. Wacht `Retry-After` seconden; een sleutel die onlangs werkte, wordt niet geblokkeerd.

Response401

{
  "error": {
    "code": "apikey.invalid",
    "message": "The API key is not valid. It may have been revoked; create a new one in the project under API Keys."
  }
}

Verwerkingsmodi

Elke upload wordt op een van vier manieren gelezen.

Automatische categorie (auto-classify). Parsevix kiest de best passende categorie van het project en extraheert daarna de velden ervan. Wordt gebruikt als u geen categorie meestuurt, of category=auto.
Alleen classificeren (classify-only). Parsevix kiest de best passende categorie en extraheert niets, om documenten op type te sorteren. Het leest de eerste 3 pagina's en kost 1 credit per document. De velden kunnen later worden geëxtraheerd. Zie Een document classificeren.
Specifieke categorie (specific). U noemt de categorie; de velden ervan worden geëxtraheerd.
Zonder schema (auto-entity). Er wordt geen categorie gebruikt. Parsevix geeft de velden terug die het vindt, benoemd naar de eigen labels van het document. Zie Extraheren zonder schema.

De taal van het document wordt automatisch herkend. De optionele parameter language is alleen een terugvaloptie voor documenten met te weinig tekst om de taal te herkennen.

Een document extraheren

POST/api/v1/extract

Uploadt een document en wacht tot het verwerkt is. De response bevat de geëxtraheerde velden.

filefileverplicht: Het document: PDF, DOCX, PNG, JPEG of TIFF, tot 10 MB en 30 pagina's.
categorystringoptioneel: Naam van een categorie in het project. Laat de parameter weg, of stuur auto, om Parsevix te laten kiezen.
languagestringoptioneel: ISO 639-1-code van twee letters, zoals de. Wordt alleen gebruikt als de taal niet herkend kan worden.

Wachten en limieten

De request blijft open tot het resultaat klaar is, maximaal 285 seconden. Stel de time-out van uw HTTP-client hoger in.
Duurt de verwerking langer, dan krijgt u 504 met document.sync_timeout en het documentId. De verwerking gaat door; het resultaat gaat naar uw webhooks.
Mislukt de verwerking, dan krijgt u 422 met document.sync_failed. reason geeft de oorzaak; zie oorzaken van mislukking.
Per API-sleutel kunnen 5 requests tegelijk open staan. Meer requests krijgen 429 met document.sync_concurrency_limit. Een request dat u afbreekt, of dat een time-out krijgt, houdt zijn plaats tot het document is verwerkt. Gebruik voor bulkuploads de asynchrone upload.

Response

idstring: Document-id.
fileNamestring: De naam van het geüploade bestand.
statusstring: Completed.
categorystring | null: De gebruikte categorie; null zonder schema.
processingModestring: auto-classify, specific of auto-entity.
confidenceScorenumber: Tussen 0 en 1: hoe zeker de extractie is.
pageCountinteger: Verwerkte pagina's; elke pagina kost één credit.
languagestring: Herkende taal, ISO 639-1.
retainedboolean: Of Parsevix het bestand en het resultaat bewaart. Zie Gegevensbewaring.
extractedobject: De geëxtraheerde velden. Zie Het resultaat.

curl https://parsevix.com/api/v1/extract \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf \
  -F category="Supplier invoice"

Response200· ingekort

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "specific",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "language": "en",
  "retained": false,
  "extracted": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

Response422

{
  "error": {
    "code": "document.sync_failed",
    "message": "The file is damaged or is not a valid PDF, Word document or image.",
    "reason": "file_unreadable",
    "documentId": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581"
  }
}

Response504

{
  "error": {
    "code": "document.sync_timeout",
    "message": "Extraction did not finish within 285 seconds. Large documents may need to be split.",
    "documentId": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581"
  }
}

Extraheren zonder schema

POST/api/v1/extract-auto

Zoals POST /extract, maar zonder categorie: Parsevix geeft alle velden terug die het in het document vindt.

filefileverplicht: Het document: PDF, DOCX, PNG, JPEG of TIFF, tot 10 MB en 30 pagina's.
languagestringoptioneel: ISO 639-1-code van twee letters. Wordt alleen gebruikt als de taal niet herkend kan worden.

De uitvoer blijft in de taal van het document. Sleutels zijn de eigen labels van het document in snake_case (een Duitse factuur geeft rechnungsnummer), en waarden worden overgenomen zoals ze gedrukt staan: datums in het formaat van het document, bedragen als strings zoals "2.430,09".

Gebruik dit om een nieuw documenttype te verkennen. Voor gegevens die u automatisch verwerkt, geeft een categorie u vaste sleutels en genormaliseerde waarden.

De response heeft dezelfde velden als POST /extract, met processingMode auto-entity en category null.

curl https://parsevix.com/api/v1/extract-auto \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf

Een document classificeren

POST/api/v1/classify

Uploadt een document en wacht tot Parsevix een van de categorieën van het project heeft gekozen. Er worden geen velden geëxtraheerd. Gebruik dit om documenten op type te sorteren of door te sturen.

De kandidaten zijn de eigen categorieën van het project, niet de ingebouwde sjablonen. Parsevix leest de eerste 3 pagina's, dus een classificatie kost 1 credit, hoe lang het document ook is.

filefileverplicht: Het document: PDF, DOCX, PNG, JPEG of TIFF, tot 10 MB en 30 pagina's.
languagestringoptioneel: ISO 639-1-code van twee letters. Wordt alleen gebruikt als de taal niet herkend kan worden.

Wachten en fouten werken zoals bij POST /extract: maximaal 285 seconden, 504 met document.sync_timeout als het langer duurt, 422 met document.sync_failed als het document niet verwerkt kan worden. De 5 open requests per sleutel worden door beide endpoints gedeeld.

Response

idstring: Document-id.
fileNamestring: De naam van het geüploade bestand.
statusstring: Completed.
categorystring: De categorie die Parsevix heeft gekozen.
processingModestring: classify-only.
pageCountinteger: Pagina's in het document. De eerste 3 zijn gelezen.
languagestring: Herkende taal, ISO 639-1.
retainedboolean: Of Parsevix het bestand bewaart. Alleen een bewaard document kan later worden geëxtraheerd.

Later extraheren

POST /documents/{id}/extract extraheert de velden van het document, volgens de categorie die het kreeg of een categorie die u noemt. Het kost het aantal pagina's van het document min de al betaalde 1 credit: een document van 5 pagina's kost nog 4, in totaal 5.

Daarvoor is het bestand nodig, dus het project moet API-uploads bewaren (zie Gegevensbewaring). Documenten die via het dashboard of per e-mail zijn verstuurd, worden altijd bewaard. Asynchrone uploads kunnen ook geclassificeerd worden: processingMode=classify-only bij POST /documents.

curl https://parsevix.com/api/v1/classify \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf

Response200

{
  "id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "classify-only",
  "pageCount": 1,
  "language": "en",
  "retained": true
}

Asynchroon uploaden

POST/api/v1/documents

Zet een document in de wachtrij en antwoordt direct met 202 en het documentrecord. Gebruik dit voor bulkuploads en voor clients die een request niet open kunnen houden, zoals Zapier.

filefileverplicht: Het document: PDF, DOCX, PNG, JPEG of TIFF, tot 10 MB en 30 pagina's.
categorystringoptioneel: Naam van een categorie. Laat de parameter weg, of stuur auto, om Parsevix te laten kiezen.
processingModestringoptioneel: auto-classify, specific, auto-entity of classify-only. Optioneel: standaard volgt de modus uit category. classify-only kan niet met een categorie worden gecombineerd.
languagestringoptioneel: ISO 639-1-code van twee letters. Wordt alleen gebruikt als de taal niet herkend kan worden.
callbackUrlstringoptioneel: Een openbare https-URL. Parsevix stuurt het resultaat er één keer naartoe, als POST met dezelfde body als een webhook-event.

Het resultaat ophalen

Webhooks van het project ontvangen extraction.completed of extraction.failed. Een classify-only-upload stuurt classification.completed in plaats van extraction.completed.
callbackUrl ontvangt, indien opgegeven, hetzelfde event, met dezelfde nieuwe pogingen. Het is niet ondertekend; neem dus een geheim token op in de URL en controleer dat.
Polling met GET /documents/{id} toont de status, en het resultaat alleen als het project API-uploads bewaart (zie Gegevensbewaring).

curl https://parsevix.com/api/v1/documents \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf \
  -F category="Supplier invoice" \
  -F callbackUrl="https://example.com/parsevix/callback?token=a-secret-only-you-know"

Response202

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "status": "Pending",
  "categoryName": "Supplier invoice",
  "processingMode": "specific",
  "fileName": "invoice.pdf",
  "fileSize": 22579,
  "source": "api",
  "discardFiles": true,
  "createdAt": "2026-10-25T10:12:06.791Z",
  "completedAt": null,
  "reprocessCount": 0,
  "lastReprocessedAt": null,
  "approvalStatus": "Unapproved",
  "isTrainingExample": false
}

Het resultaat

extracted

Een object met de veldnamen van de categorie als sleutels (fieldName in het categorieschema). Objecten en lijsten volgen het schema.

Datums zijn YYYY-MM-DD. Getallen zijn JSON-getallen, zonder valutasymbolen of scheidingstekens voor duizendtallen. Een veld dat niet in het document staat, ontbreekt of is null.

Persoonsgegevens zoals namen en IBAN's worden teruggegeven zoals ze in het document staan. Ze worden alleen gemaskeerd op weg naar het AI-model en hersteld voordat u ze ontvangt.

_field_blocks

Waar elke waarde is gevonden. Sleutels zijn veldpaden zoals seller.name of line_items[0].total; elk item somt de tekstregels op met pagina, kader en tekst. Een waarde die niet gelokaliseerd kon worden, ontbreekt hierin. Negeer sleutels die met _ beginnen als u alleen de gegevens nodig hebt.

Coördinaten

PDF en DOCX: PDF-punten (1/72 inch). De oorsprong is de linkerbenedenhoek van de pagina; y is de bovenrand van het kader, gemeten vanaf onderen.
Afbeeldingen: pixels. De oorsprong is de linkerbovenhoek; y is de bovenrand, gemeten vanaf boven.

extracted200· ingekort

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "specific",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "language": "en",
  "retained": false,
  "extracted": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

Documenten

Documenten van het project, uit elke bron: het dashboard, de API en e-mail.

Documenten opvragen

GET/api/v1/documents

Nieuwste eerst. Toont alleen opgeslagen documenten: API-uploads verschijnen alleen als het project ze bewaart.

pageintegeroptioneel: Paginanummer, vanaf 1.
pageSizeintegeroptioneel: 1 tot 100; standaard 20.
statusstringoptioneel: Pending, Processing, Completed of Failed.
categorystringoptioneel: Naam van de categorie.
searchstringoptioneel: Deel van de bestandsnaam.
fileTypestringoptioneel: pdf, docx of image.
sourcestringoptioneel: dashboard, api of email.
processingModestringoptioneel: auto-classify, specific, auto-entity of classify-only.

Een document opvragen

GET/api/v1/documents/{id}

Het document met het resultaat. outputDeanonymized zijn de geëxtraheerde gegevens, hetzelfde object als extracted. Een classify-only-document heeft zijn categorie in categoryName en geen outputDeanonymized. Een mislukt document heeft errorCode en errorMessage. Als het project API-uploads niet bewaart, is de status beschikbaar, maar het resultaat niet.

Een document opnieuw verwerken

POST/api/v1/documents/{id}/reprocess

Voert de extractie opnieuw uit, bijvoorbeeld nadat u de velden van de categorie hebt gewijzigd. Optionele JSON-body: category (een naam, of auto) en processingMode. Antwoordt met 202; het resultaat komt binnen zoals bij een asynchrone upload. Er worden opnieuw credits in rekening gebracht. Een classify-only-document wordt opnieuw geclassificeerd (1 credit), tenzij u een categorie noemt. Niet mogelijk voor API-uploads waarvan de bestanden niet zijn bewaard (document.files_not_retained).

Een geclassificeerd document extraheren

POST/api/v1/documents/{id}/extract

Voor een document dat met classify-only is geüpload: extraheert de velden volgens de categorie die het kreeg, of volgens de category die in de optionele JSON-body wordt genoemd. Kost het aantal pagina's van het document min de 1 credit die de classificatie kostte. Antwoordt met 202; het resultaat komt binnen zoals bij een asynchrone upload, als extraction.completed. Voor elk ander document antwoordt het met 400 en document.not_classify_only; gebruik dan opnieuw verwerken.

Een document verwijderen

DELETE/api/v1/documents/{id}

Verwijdert het document, het bestand en de resultaten. Antwoordt met 204.

Een id die niet bestaat in het project van de sleutel geeft 404 met document.not_found.

cURL

curl "https://parsevix.com/api/v1/documents?status=Completed&pageSize=20" \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Response200· ingekort

{
  "data": [
    {
      "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
      "status": "Completed",
      "categoryName": "Supplier invoice",
      "processingMode": "specific",
      "fileName": "invoice.pdf",
      "fileSize": 22579,
      "source": "api",
      "discardFiles": false,
      "createdAt": "2026-10-25T10:12:06.791Z",
      "completedAt": "2026-10-25T10:12:15.212Z",
      "reprocessCount": 0,
      "lastReprocessedAt": null,
      "approvalStatus": "Unapproved",
      "isTrainingExample": false
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 20
}

curl https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581 \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Response200· ingekort

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "status": "Completed",
  "categoryName": "Supplier invoice",
  "processingMode": "specific",
  "fileName": "invoice.pdf",
  "fileSize": 22579,
  "source": "api",
  "language": "en",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "outputDeanonymized": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  },
  "errorMessage": null,
  "errorCode": null,
  "createdAt": "2026-10-25T10:12:06.791Z",
  "completedAt": "2026-10-25T10:12:15.212Z"
}

cURL

curl https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581/reprocess \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category": "auto"}'

cURL

curl https://parsevix.com/api/v1/documents/01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27/extract \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response202

{
  "id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
  "status": "Pending",
  "categoryName": "Supplier invoice",
  "processingMode": "specific",
  "fileName": "invoice.pdf",
  "fileSize": 22579,
  "source": "api",
  "discardFiles": false,
  "createdAt": "2026-10-25T10:12:06.791Z",
  "completedAt": null,
  "reprocessCount": 1,
  "lastReprocessedAt": "2026-10-25T11:04:12.530Z",
  "approvalStatus": "Unapproved",
  "isTrainingExample": false
}

cURL

curl -X DELETE https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581 \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Categorieën

De categorieën van het project, inclusief de ingebouwde sjablonen (isGlobal: true). Categorieën worden in het dashboard aangemaakt en bewerkt.

Categorieën opvragen

GET/api/v1/categories

Het schema van een categorie opvragen

GET/api/v1/categories/{name}

De velden die een categorie extraheert. fieldName is de sleutel in extracted. fieldType is string, number, date, boolean, object of array; objecten en arrays hebben hun velden in children. De naam in het pad is niet hoofdlettergevoelig.

cURL

curl https://parsevix.com/api/v1/categories \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Response200· ingekort

[
  {
    "id": 1,
    "name": "Invoice",
    "description": "Invoices and billing documents with seller/buyer info, line items, and totals",
    "isGlobal": true,
    "fieldCount": 48
  },
  {
    "id": 54,
    "name": "Supplier invoice",
    "description": "Commercial invoice: seller, buyer, line items and totals.",
    "isGlobal": false,
    "fieldCount": 26
  }
]

cURL

curl "https://parsevix.com/api/v1/categories/Supplier%20invoice" \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Response200· ingekort

{
  "id": 54,
  "name": "Supplier invoice",
  "description": "Commercial invoice: seller, buyer, line items and totals.",
  "fields": [
    {
      "fieldName": "invoice_number",
      "displayName": "Invoice number",
      "fieldType": "string",
      "description": null,
      "children": []
    },
    {
      "fieldName": "invoice_date",
      "displayName": "Invoice date",
      "fieldType": "date",
      "description": null,
      "children": []
    },
    {
      "fieldName": "seller",
      "displayName": "Seller",
      "fieldType": "object",
      "description": null,
      "children": [
        {
          "fieldName": "name",
          "displayName": "Name",
          "fieldType": "string",
          "description": null,
          "children": []
        },
        {
          "fieldName": "vat_id",
          "displayName": "VAT / tax id",
          "fieldType": "string",
          "description": null,
          "children": []
        }
      ]
    }
  ]
}

Sleutel en credits

GET/api/v1/me

Het project van de sleutel en het creditsaldo van het account. Credits horen bij het account en worden gedeeld door al zijn projecten; resetsOn is het begin van de volgende periode. Bij een jaarabonnement is de periode het factuurjaar en bevat monthlyLimit de credits van het hele jaar.

cURL

curl https://parsevix.com/api/v1/me \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Response200

{
  "projectId": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "projectName": "Accounts payable",
  "projectSlug": "accounts-payable",
  "keyName": "ERP connector",
  "keyPrefix": "psvx_nyskxlv",
  "email": "you@example.com",
  "credits": {
    "period": "2026-10-04",
    "resetsOn": "2026-11-04",
    "monthlyLimit": 1000,
    "used": 312,
    "remaining": 688,
    "planName": "Growth"
  }
}

Webhooks beheren

Webhooks kunnen in het dashboard (Webhooks) of via deze endpoints worden beheerd.

Een webhook aanmaken

POST/api/v1/webhooks

urlstringverplicht: Een openbare https-URL. Adressen in privénetwerken worden geweigerd.
eventsstring[]verplicht: Een of meer van extraction.completed, extraction.failed en classification.completed.
filtersobjectoptioneel: Optioneel. sources (dashboard, api, email) en categories (namen) beperken voor welke documenten events worden verstuurd.

De response bevat het ondertekeningsgeheim secret één keer. Bewaar het om handtekeningen te verifiëren.

Webhooks opvragen

GET/api/v1/webhooks

Een webhook verwijderen

DELETE/api/v1/webhooks/{id}

Voorbeeldevents

GET/api/v1/webhooks/samples

De nieuwste documenten van het project als event-bodies, om uw ontvanger te testen. Query: event (verplicht), limit (1–10, standaard 3), category. Als er nog geen passend document is, wordt een voorbeeld opgebouwd uit het categorieschema.

cURL

curl https://parsevix.com/api/v1/webhooks \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/parsevix/webhook",
    "events": ["extraction.completed", "extraction.failed"],
    "filters": { "sources": ["api", "email"] }
  }'

Response201

{
  "secret": "d0726faeb5c655d349fc30ed226e93e531ac2499800aacde100e83554b48701c",
  "id": "01a17295-c761-7b8f-b173-388bc754b1ba",
  "url": "https://example.com/parsevix/webhook",
  "events": [
    "extraction.completed",
    "extraction.failed"
  ],
  "filters": {
    "sources": [
      "api",
      "email"
    ],
    "categories": null
  },
  "isActive": true,
  "disabledAt": null,
  "disabledReason": null,
  "managedBy": null,
  "createdAt": "2026-10-25T10:23:09.311Z"
}

cURL

curl "https://parsevix.com/api/v1/webhooks/samples?event=extraction.completed&limit=1" \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Webhooks

Wanneer een document klaar is, stuurt Parsevix een POST met een JSON-body naar elke webhook van het project. Webhooks ontvangen documenten uit elke bron: dashboard, API en e-mail.

Events

Event	Beschrijving
extraction.completed	Een document is verwerkt. `data` bevat de geëxtraheerde velden.
classification.completed	Een `classify-only`-document heeft zijn categorie gekregen: `document.category`, met het aantal pagina's van het document in `document.page_count`. Er is geen `data`.
extraction.failed	Een document kon niet worden verwerkt, ook een `classify-only`-document. `error_code` is een van de oorzaken van mislukking; `error` is de melding die in het dashboard wordt getoond.
test.ping	Verstuurd door de knop Testen op de pagina van een webhook in het dashboard.

Headers

Header	Beschrijving
X-Webhook-Id	Event-id. Gelijk bij elke poging; gebruik het om duplicaten te negeren. Ook de `id` in de body.
X-Webhook-Event	De naam van het event.
X-Webhook-Timestamp	Unix-tijd van deze poging, in seconden.
X-Webhook-Signature	`sha256=` gevolgd door de hexadecimale HMAC-SHA256 van `{timestamp}.{raw body}`, met het geheim van de webhook als sleutel.
X-Webhook-Attempt	Nummer van de poging, vanaf 1.

De handtekening verifiëren

Bereken de HMAC over de ruwe request-body precies zoals ontvangen, voordat u die parseert. Weiger events waarvan de tijdstempel meer dan 5 minuten oud is.

Antwoorden

Antwoord binnen 10 seconden met een 2xx-status en verwerk het event daarna. Al het andere telt als mislukking. Redirects worden niet gevolgd.
Mislukte afleveringen worden opnieuw geprobeerd na 1 minuut, 5 minuten, 30 minuten, 2 uur, 6 uur en 24 uur: 7 pogingen in ongeveer 33 uur.
Antwoorden met 410 Gone schakelt de webhook direct uit. Hij wordt ook uitgeschakeld wanneer drie events bij elke poging zijn mislukt en er 3 dagen lang geen aflevering is gelukt. De eigenaar krijgt een e-mail; schakel de webhook in het dashboard weer in. Events uit de tussentijd worden niet opnieuw verstuurd.
Het geheim kan in het dashboard worden vernieuwd. Het oude geheim werkt dan direct niet meer.

extraction.completed200· ingekort

{
  "id": "01a172a0-3f1e-7d42-9b6c-8e2f5a7d1c90",
  "event": "extraction.completed",
  "timestamp": "2026-10-25T10:12:21.592Z",
  "project_id": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "project_name": "Accounts payable",
  "project_slug": "accounts-payable",
  "document": {
    "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
    "file_name": "invoice.pdf",
    "category": "Supplier invoice",
    "source": "api",
    "processing_mode": "specific",
    "language": "en",
    "confidence_score": 0.97
  },
  "data": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

classification.completed200

{
  "id": "01a172b5-8e47-7a13-b2c9-4f6d0a8e3b51",
  "event": "classification.completed",
  "timestamp": "2026-10-25T10:14:02.334Z",
  "project_id": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "project_name": "Accounts payable",
  "project_slug": "accounts-payable",
  "document": {
    "id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
    "file_name": "invoice.pdf",
    "category": "Supplier invoice",
    "source": "api",
    "processing_mode": "classify-only",
    "language": "en",
    "page_count": 1
  }
}

extraction.failed200

{
  "id": "01a172a1-0c55-7e18-a3d4-6b9f2e8c1d07",
  "event": "extraction.failed",
  "timestamp": "2026-10-25T10:12:23.711Z",
  "project_id": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "project_name": "Accounts payable",
  "project_slug": "accounts-payable",
  "document": {
    "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
    "file_name": "invoice.pdf",
    "category": "Supplier invoice",
    "source": "api",
    "processing_mode": "specific"
  },
  "error_code": "file_unreadable",
  "error": "The file is damaged or is not a valid PDF, Word document or image."
}

import hashlib
import hmac
import time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"]  # "sha256=<hex>"
    if abs(time.time() - int(timestamp)) > 300:
        return False  # ouder dan 5 minuten: mogelijk opnieuw afgespeeld
    expected = hmac.new(
        secret.encode(),
        timestamp.encode() + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(signature, "sha256=" + expected)

Zapier

De Parsevix-app voor Zapier maakt verbinding met een API-sleutel van een project. Voeg de app toe via de uitnodigingslink op de pagina Zapier van het project in het dashboard of hier.

Triggers

Extraction Completed: een document is verwerkt. Optioneel alleen voor één categorie of bron.
Extraction Failed: een document kon niet worden verwerkt.
Document Classified: een document dat alleen voor classificatie is verstuurd, heeft zijn categorie gekregen, bijvoorbeeld via een e-mailadres dat op alleen classificeren is ingesteld.

Acties

Extract Document verstuurt een bestand uit een eerdere stap, optioneel met een categorie, en geeft de geëxtraheerde velden door aan de volgende stappen. Met een gekozen categorie kunnen de velden ervan worden gekoppeld terwijl u de Zap bouwt.
Classify Document verstuurt een bestand en geeft de door Parsevix gekozen categorie door aan de volgende stappen, zonder velden te extraheren. Gebruik dit om documenten op type door te sturen.

Zaps die u inschakelt, verschijnen op de pagina Zapier van het project en onder Webhooks.

E-mail

Vanaf het Starter-abonnement heeft elk project een e-mailadres onder E-mailinbox. Elke bijlage van een e-mail die daarheen wordt gestuurd, wordt een document; de resultaten verschijnen in het dashboard en worden naar uw webhooks gestuurd met bron email.

Adressen zien eruit als name+inbox@inbox.parsevix.com. Afhankelijk van het abonnement kan een project er meer dan één hebben, bijvoorbeeld één per leverancier of afdeling.

Per adres

Bijlagen: elke bijlage extraheren volgens één vaste categorie; Parsevix de categorie laten kiezen en daarna extraheren; of alleen de categorie kiezen (classify-only, 1 credit per document), met de velden later geëxtraheerd als u ze nodig hebt.
Toegestane afzenders: alleen e-mail van deze domeinen wordt geaccepteerd, en alleen als die voor dat domein DKIM of SPF doorstaat, zodat een vervalste afzender wordt geweigerd.

Wat wordt verwerkt

Bijlagen in PDF, DOCX, PNG, JPEG en TIFF, ook die in doorgestuurde e-mails. Afbeeldingen in de tekst van de e-mail, zoals logo's in handtekeningen, worden overgeslagen.
Een e-mail mag maximaal 30 MB groot zijn, en de eerste 20 bijlagen worden documenten. Eén adres neemt binnen 24 uur maximaal 1.000 e-mails aan en maakt maximaal 1.000 documenten; daarboven wordt e-mail geweigerd en worden bijlagen als niet geïmporteerd vermeld. Ontvangen is gratis; elk document kost credits zoals elk ander document.
Dezelfde e-mail die twee keer wordt afgeleverd (zelfde Message-ID), wordt één keer verwerkt.

Fouten

Fouten hebben een HTTP-status en een body met een vaste code en een leesbare message. Baseer uw logica op code; meldingen kunnen veranderen.

Statuscodes

Status	Betekenis
400	De request is ongeldig: een ontbrekende of onjuiste parameter, een niet-ondersteund bestand, te weinig credits. `validation.failed` somt de problemen per parameter op in `fields`.
401	Geen API-sleutel, of geen geldige.
403	De sleutel is geldig, maar mag niet worden gebruikt. Zie Authenticatie.
404	Het document, de categorie, de webhook of het endpoint bestaat niet in dit project.
413	De upload is groter dan de limiet voor requests.
422	`POST /extract` of `POST /classify` is uitgevoerd, maar het document kon niet worden verwerkt.
429	Rate limit of limiet voor gelijktijdige requests bereikt. Wacht `Retry-After` seconden.
5xx	Een serverfout (met een referentie om aan support door te geven), onderhoud (`503`) of een time-out (`504`).

Veelvoorkomende codes

Code	Betekenis
validation.file_required	Er is geen `file` meegestuurd.
document.content_not_supported	De inhoud van het bestand is geen PDF, DOCX, PNG, JPEG of TIFF, wat de naam ook zegt.
credit.file_size_exceeds_plan	Het bestand is groter dan het abonnement toestaat.
validation.language_invalid	`language` is geen code van twee letters.
document.callback_url_*	`callbackUrl` is geen openbare `https`-URL van maximaal 2.000 tekens.
credit.insufficient_credits	Niet genoeg credits meer over in deze periode.
document.refund_pending	Een terugbetaling van het abonnement wordt beoordeeld; er wordt niets verwerkt tot die is afgehandeld.
category.not_found	Geen categorie met die naam in het project.
document.classify_only_category	`classify-only` is samen met een categorie meegestuurd. Deze modus kiest de categorie zelf.
document.not_classify_only	`POST /documents/{id}/extract` is aangeroepen voor een document dat niet met `classify-only` is geüpload.
document.files_not_retained	De bestanden van de API-upload zijn niet bewaard, dus die kan niet opnieuw worden verwerkt.
webhook.url_*	De webhook-URL is geen openbare `https`-URL.
*.limit_reached	Een limiet van het abonnement is bereikt, zoals het aantal webhooks per project.

Oorzaken van mislukking

Waarom een document is mislukt: reason in de 422 van POST /extract of POST /classify, error_code in extraction.failed, errorCode bij het document.

Code	Betekenis
too_many_pages	Meer dan 30 pagina's. Splits het bestand.
sync_too_many_pages	Meer pagina's dan `POST /extract` en `POST /classify` accepteren.
pdf_encrypted	De PDF is met een wachtwoord beveiligd.
file_unreadable	Het bestand is beschadigd of geen geldig document.
no_text	Er is geen tekst gevonden: leeg, of de scan is onleesbaar.
no_categories	De categorie zou automatisch worden gekozen, maar het project heeft geen categorieën.
no_schema_fields	De categorie heeft geen velden.
no_fields_found	Geen van de velden van de categorie is in het document gevonden; het staat waarschijnlijk in de verkeerde categorie. Verwerk het opnieuw met de juiste.
no_data_found	De automatische extractie heeft geen gegevens in het document gevonden.
insufficient_credits	Het document heeft meer credits nodig dan er in deze periode over zijn. Er is niets in rekening gebracht; verwerk het opnieuw na een upgrade of de reset.
refund_pending	Er werd een terugbetaling van het abonnement beoordeeld. Als die wordt afgewezen, verwerk het document dan opnieuw.
masking_failed	Persoonsgegevens konden niet worden gemaskeerd, dus het document is niet naar het AI-model gestuurd. Probeer het opnieuw.
worker_unavailable	De verwerking was tijdelijk niet beschikbaar. Probeer het opnieuw.
ai_failed	Het AI-model is tijdelijk mislukt. Probeer het opnieuw.
processing_failed	Een interne fout. Probeer het opnieuw; neem contact op met support als het zich herhaalt.
processing_timeout	De verwerking is gestopt voordat die klaar was (bijvoorbeeld tijdens een herstart). Probeer het opnieuw.

De laatste vijf zijn tijdelijk: verwerk het document opnieuw of stuur het nogmaals. Voor mislukte runs worden geen pagina's in rekening gebracht.

Response400

{
  "error": {
    "code": "validation.failed",
    "message": "The file field is required.",
    "fields": {
      "file": [
        "The file field is required."
      ]
    }
  }
}

Response422

{
  "error": {
    "code": "document.sync_failed",
    "message": "The file is damaged or is not a valid PDF, Word document or image.",
    "reason": "file_unreadable",
    "documentId": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581"
  }
}

Limieten en credits

Bestanden

PDF, DOCX, PNG, JPEG en TIFF (ook met meerdere pagina's). Het type wordt bepaald aan de hand van de inhoud van het bestand, niet de naam.
Tot 10 MB en 30 pagina's per document.

Credits

Elke verwerkte pagina kost 1 credit. Automatisch de categorie kiezen kost niets extra.
Alleen classificeren (classify-only) kost 1 credit per document. Zo'n document later extraheren kost het aantal pagina's min die credit, dus het totaal blijft 1 credit per pagina.
Een mislukte run kost niets voor de pagina's. Opnieuw verwerken kost opnieuw credits. E-mail ontvangen is gratis.
Wanneer de credits van een periode op zijn, worden uploads geweigerd met credit.insufficient_credits tot de volgende periode of een upgrade. De credits van een document worden gereserveerd zodra de pagina's zijn geteld; als ze dan niet meer passen, bijvoorbeeld na veel parallelle uploads, mislukt het document met insufficient_credits en wordt er niets in rekening gebracht.

Aantal requests

Elke API-sleutel mag per minuut een aantal requests doen, afhankelijk van het abonnement. Elke response bevat X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset (Unix-tijd). Boven de limiet krijgt u 429 met Retry-After.

Per abonnement

Abonnement	Requests / minuut	Credits / maand	API-sleutels	Webhooks / project
Free	10	20	1	1
Starter	30	500	2	2
Growth	60	2.000	3	5
Pro	120	6.000	10	10
Business	300	20.000	onbeperkt	25

Verder: POST /extract en POST /classify wachten maximaal 285 seconden en staan samen 5 open requests per sleutel toe.

Response429

{
  "error": {
    "code": "apikey.rate_limited",
    "message": "Too many requests for this API key: the limit is 60 per minute. Retry in 18 s.",
    "limit": 60,
    "retryAfterSeconds": 18
  }
}

Gegevensbewaring

Wat Parsevix van een API-upload bewaart, is een projectinstelling: API-uploads, onder Projectinstellingen. Standaard staat deze op Verwijderen na verwerking; met Bewaren zoals dashboarduploads blijven ze bewaard.

Verwijderen na verwerking: het bestand wordt verwijderd zodra de verwerking klaar is en het resultaat wordt niet opgeslagen. De API-response, webhook of callback is de enige kopie. Zulke documenten worden niet weergegeven en kunnen niet opnieuw worden verwerkt of gedownload; retained is false.
Bewaren zoals dashboarduploads: bestanden en resultaten worden opgeslagen zoals dashboarduploads, totdat u ze verwijdert.

Uploads via het dashboard en per e-mail worden altijd opgeslagen. Persoonsgegevens worden gemaskeerd voordat er tekst naar het AI-model gaat; zie Beveiliging.