API-Dokumentation
Senden Sie ein PDF, ein Word-Dokument oder ein Bild und erhalten Sie strukturiertes JSON zurück.
Einführung
Die gewünschten Daten beschreiben Sie als Kategorie: eine Liste von Feldern wie Rechnungsnummer, Datum oder Positionen, angelegt im Dashboard. Parsevix liest das Dokument, füllt diese Felder und gibt sie als JSON zurück, zusammen mit dem gelesenen Text und der Fundstelle jedes Werts.
Die API ist per HTTPS unter einer Basis-URL erreichbar. Anfragen und Antworten sind JSON, außer Datei-Uploads, die als multipart/form-data gesendet werden.
https://parsevix.com/api/v1Jeder API-Schlüssel gehört zu einem Projekt. Ein Schlüssel sieht und ändert nur die Dokumente, Kategorien und Webhooks dieses Projekts.
Neben API-Aufrufen können Sie Ergebnisse über Webhooks empfangen, Zapier verbinden oder Dokumente an die E-Mail-Adresse eines Projekts senden.
Konventionen
- API-Antworten verwenden Feldnamen in camelCase. Webhook- und Callback-Inhalte verwenden snake_case.
- Zeitangaben sind UTC im Format ISO 8601 (
2026-10-25T10:12:06.791Z). - Fehlermeldungen gibt es auf Englisch, Deutsch, Türkisch, Französisch, Spanisch, Italienisch, Niederländisch, Polnisch und Portugiesisch, je nach
Accept-Language-Header.
Schnellstart
- 1
API-Schlüssel erstellen
Öffnen Sie im Dashboard Ihr Projekt, gehen Sie zu API-Schlüssel und erstellen Sie einen Schlüssel. Er wird nur einmal angezeigt; speichern Sie ihn, zum Beispiel als Umgebungsvariable
PARSEVIX_API_KEY. Der Free-Tarif enthält einen Schlüssel, bezahlte Tarife mehr (siehe Grenzen und Credits). - 2
Kategorie anlegen
Legen Sie unter Kategorien eine Kategorie für Ihren Dokumenttyp an und fügen Sie die benötigten Felder hinzu, oder beginnen Sie mit einer eingebauten Vorlage. Die Beispiele auf dieser Seite verwenden eine Kategorie namens
Supplier invoice. - 3
Dokument senden
POST /extractlädt die Datei hoch und wartet auf das Ergebnis. Die Antwort enthält die gefüllten Felder unterextracted.
Um viele Dokumente zu verarbeiten, ohne Anfragen offen zu halten, laden Sie asynchron hoch und empfangen die Ergebnisse über Webhooks.
curl https://parsevix.com/api/v1/extract \
-H "X-API-Key: $PARSEVIX_API_KEY" \
-F file=@invoice.pdf \
-F category="Supplier invoice"{
"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"
}
]
}
}
}Video-Tutorials
Fünf kurze Videos zeigen die wichtigsten Schritte im Dashboard und Ihre erste API-Anfrage. Jedes hat Sprecherton und Untertitel in neun Sprachen: Sie wählen sie im Player unter dem Zahnrad-Symbol.
Die Videos werden von YouTube abgespielt (youtube-nocookie.com). Bis Sie auf Abspielen klicken, wird nichts von YouTube geladen; danach erhält Google Ihre IP-Adresse und kann Cookies speichern. Siehe unsere Datenschutzerklärung.
Authentifizierung
Senden Sie Ihren API-Schlüssel bei jeder Anfrage im Header X-API-Key.
X-API-Key: psvx_…Ein Schlüssel gilt nur für /api/v1; mit ihm kann man sich nicht im Dashboard anmelden. Schlüssel werden im Projekt unter API-Schlüssel erstellt und widerrufen. Ein widerrufener Schlüssel ist sofort ungültig.
Bewahren Sie Schlüssel auf Ihrem Server auf. Wer einen Schlüssel hat, kann Dokumente hochladen und die Ergebnisse des Projekts lesen, und die Uploads verbrauchen Ihre Credits.
Wann ein Schlüssel abgelehnt wird
| Status | Code | Bedeutung |
|---|---|---|
| 401 | apikey.missing | Es wurde kein X-API-Key-Header gesendet. |
| 401 | apikey.invalid | Den Schlüssel gibt es nicht oder er wurde widerrufen. |
| 403 | apikey.plan_disabled | Der Tarif des Kontos enthält keinen API-Zugang. |
| 403 | apikey.paused_by_plan | Der Schlüssel oder sein Projekt ist pausiert, weil der Tarif des Kontos weniger Schlüssel oder Projekte erlaubt. |
| 403 | apikey.account_unavailable | Das Konto ist geschlossen oder zur Löschung vorgemerkt. |
| 403 | apikey.project_unavailable | Das Projekt des Schlüssels wurde gelöscht. |
| 429 | apikey.too_many_invalid | Aus Ihrem Netzwerk kamen innerhalb von 10 Minuten mehr als 30 ungültige Schlüssel. Warten Sie Retry-After Sekunden; ein Schlüssel, der kürzlich funktioniert hat, wird nicht gesperrt. |
{
"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."
}
}Verarbeitungsarten
Jeder Upload wird auf eine von vier Arten gelesen.
- Automatische Kategorie (
auto-classify). Parsevix wählt die passendste Kategorie des Projekts und extrahiert dann deren Felder. Gilt, wenn Sie keine Kategorie odercategory=autosenden. - Nur klassifizieren (
classify-only). Parsevix wählt die passendste Kategorie und extrahiert nichts, zum Sortieren von Dokumenten nach Art. Gelesen werden die ersten 3 Seiten; es kostet 1 Credit pro Dokument. Die Felder lassen sich später extrahieren. Siehe Dokument klassifizieren. - Bestimmte Kategorie (
specific). Sie nennen die Kategorie; deren Felder werden extrahiert. - Ohne Schema (
auto-entity). Es wird keine Kategorie verwendet. Parsevix gibt die gefundenen Felder zurück, benannt nach den Beschriftungen im Dokument. Siehe Ohne Schema extrahieren.
Die Sprache des Dokuments wird automatisch erkannt. Der optionale Parameter language ist nur ein Ersatz für Dokumente mit zu wenig Text für die Erkennung.
Dokument extrahieren
/api/v1/extractLädt ein Dokument hoch und wartet, bis es verarbeitet ist. Die Antwort enthält die extrahierten Felder.
filefilePflicht- Das Dokument: PDF, DOCX, PNG, JPEG oder TIFF, bis 10 MB und 30 Seiten.
categorystringoptional- Name einer Kategorie im Projekt. Weglassen oder
autosenden, damit Parsevix sie wählt. languagestringoptional- Zweistelliger ISO-639-1-Code wie
de. Wird nur verwendet, wenn die Sprache nicht erkannt werden kann.
Wartezeit und Grenzen
- Die Anfrage bleibt offen, bis das Ergebnis vorliegt, höchstens 285 Sekunden. Stellen Sie das Timeout Ihres HTTP-Clients höher ein.
- Dauert die Verarbeitung länger, erhalten Sie
504mitdocument.sync_timeoutund derdocumentId. Die Verarbeitung läuft weiter; das Ergebnis geht an Ihre Webhooks. - Schlägt die Verarbeitung fehl, erhalten Sie
422mitdocument.sync_failed.reasonnennt den Grund; siehe Fehlergründe. - Pro API-Schlüssel können 5 Anfragen gleichzeitig offen sein. Weitere erhalten
429mitdocument.sync_concurrency_limit. Eine Anfrage, die Sie abbrechen oder die in den Timeout läuft, belegt ihren Platz, bis ihr Dokument verarbeitet ist. Für viele Dokumente nutzen Sie den asynchronen Upload.
Antwort
idstring- Dokument-ID.
fileNamestring- Name der hochgeladenen Datei.
statusstringCompleted.categorystring | null- Die verwendete Kategorie;
nullohne Schema. processingModestringauto-classify,specificoderauto-entity.confidenceScorenumber- Zwischen 0 und 1: wie sicher die Extraktion ist.
pageCountinteger- Verarbeitete Seiten; jede kostet einen Credit.
languagestring- Erkannte Sprache, ISO 639-1.
retainedboolean- Ob Parsevix Datei und Ergebnis speichert. Siehe Datenspeicherung.
extractedobject- Die extrahierten Felder. Siehe Das Ergebnis.
curl https://parsevix.com/api/v1/extract \
-H "X-API-Key: $PARSEVIX_API_KEY" \
-F file=@invoice.pdf \
-F category="Supplier invoice"{
"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"
}
]
}
}
}{
"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"
}
}{
"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"
}
}Ohne Schema extrahieren
/api/v1/extract-autoWie POST /extract, aber ohne Kategorie: Parsevix gibt alle Felder zurück, die es im Dokument findet.
filefilePflicht- Das Dokument: PDF, DOCX, PNG, JPEG oder TIFF, bis 10 MB und 30 Seiten.
languagestringoptional- Zweistelliger ISO-639-1-Code. Wird nur verwendet, wenn die Sprache nicht erkannt werden kann.
Die Ausgabe bleibt in der Sprache des Dokuments. Schlüssel sind die Beschriftungen des Dokuments in snake_case (eine deutsche Rechnung ergibt rechnungsnummer), Werte werden wie gedruckt übernommen: Daten im Format des Dokuments, Beträge als Text wie "2.430,09".
Nutzen Sie es, um einen neuen Dokumenttyp zu erkunden. Für Daten, die Sie automatisch weiterverarbeiten, liefert eine Kategorie feste Schlüssel und normalisierte Werte.
Die Antwort hat dieselben Felder wie bei POST /extract, mit processingMode auto-entity und category null.
curl https://parsevix.com/api/v1/extract-auto \
-H "X-API-Key: $PARSEVIX_API_KEY" \
-F file=@invoice.pdfDokument klassifizieren
/api/v1/classifyLädt ein Dokument hoch und wartet, bis Parsevix eine der Kategorien des Projekts gewählt hat. Es werden keine Felder extrahiert. Damit sortieren oder verteilen Sie Dokumente nach Art.
Zur Wahl stehen die eigenen Kategorien des Projekts, nicht die eingebauten Vorlagen. Parsevix liest die ersten 3 Seiten; eine Klassifizierung kostet daher 1 Credit, egal wie lang das Dokument ist.
filefilePflicht- Das Dokument: PDF, DOCX, PNG, JPEG oder TIFF, bis 10 MB und 30 Seiten.
languagestringoptional- Zweistelliger ISO-639-1-Code. Wird nur verwendet, wenn die Sprache nicht erkannt werden kann.
Wartezeit und Fehler wie bei POST /extract: höchstens 285 Sekunden, 504 mit document.sync_timeout, wenn es länger dauert, 422 mit document.sync_failed, wenn das Dokument nicht verarbeitet werden kann. Die 5 offenen Anfragen pro Schlüssel teilen sich beide Endpunkte.
Antwort
idstring- Dokument-ID.
fileNamestring- Name der hochgeladenen Datei.
statusstringCompleted.categorystring- Die Kategorie, die Parsevix gewählt hat.
processingModestringclassify-only.pageCountinteger- Seiten des Dokuments. Gelesen wurden die ersten 3.
languagestring- Erkannte Sprache, ISO 639-1.
retainedboolean- Ob Parsevix die Datei speichert. Nur ein gespeichertes Dokument lässt sich später extrahieren.
Später extrahieren
POST /documents/{id}/extract extrahiert die Felder des Dokuments, als die gewählte Kategorie oder als eine, die Sie nennen. Es kostet die Seiten des Dokuments abzüglich des bereits bezahlten Credits: ein Dokument mit 5 Seiten kostet 4 weitere, insgesamt 5.
Dafür wird die Datei gebraucht; das Projekt muss also API-Uploads speichern (siehe Datenspeicherung). Dokumente aus dem Dashboard oder per E-Mail werden immer gespeichert. Auch asynchrone Uploads lassen sich klassifizieren: processingMode=classify-only bei POST /documents.
curl https://parsevix.com/api/v1/classify \
-H "X-API-Key: $PARSEVIX_API_KEY" \
-F file=@invoice.pdf{
"id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
"fileName": "invoice.pdf",
"status": "Completed",
"category": "Supplier invoice",
"processingMode": "classify-only",
"pageCount": 1,
"language": "en",
"retained": true
}Asynchron hochladen
/api/v1/documentsStellt ein Dokument in die Warteschlange und antwortet sofort mit 202 und dem Dokument. Für viele Dokumente und für Clients, die keine Anfrage offen halten können, etwa Zapier.
filefilePflicht- Das Dokument: PDF, DOCX, PNG, JPEG oder TIFF, bis 10 MB und 30 Seiten.
categorystringoptional- Name einer Kategorie. Weglassen oder
autosenden, damit Parsevix sie wählt. processingModestringoptionalauto-classify,specific,auto-entityoderclassify-only. Optional: ergibt sich sonst auscategory.classify-onlylässt sich nicht mit einer Kategorie kombinieren.languagestringoptional- Zweistelliger ISO-639-1-Code. Wird nur verwendet, wenn die Sprache nicht erkannt werden kann.
callbackUrlstringoptional- Eine öffentliche
https-URL. Parsevix sendet das Ergebnis einmal dorthin, alsPOSTmit demselben Inhalt wie ein Webhook-Ereignis.
So erhalten Sie das Ergebnis
- Webhooks des Projekts erhalten
extraction.completedoderextraction.failed. Einclassify-only-Upload sendetclassification.completedstattextraction.completed. - callbackUrl erhält, falls angegeben, dasselbe Ereignis mit denselben Wiederholungen. Es ist nicht signiert; nehmen Sie daher ein geheimes Token in die URL auf und prüfen Sie es.
- Abfragen mit
GET /documents/{id}zeigt den Status, das Ergebnis aber nur, wenn das Projekt API-Uploads speichert (siehe Datenspeicherung).
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"{
"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
}Das Ergebnis
extracted
Ein Objekt mit den Feldnamen der Kategorie als Schlüsseln (fieldName im Kategorie-Schema). Objekte und Listen folgen dem Schema.
Daten haben das Format YYYY-MM-DD. Zahlen sind JSON-Zahlen ohne Währungszeichen und Tausendertrennzeichen. Ein Feld, das im Dokument nicht vorkommt, fehlt oder ist null.
Personenbezogene Daten wie Namen und IBANs werden so zurückgegeben, wie sie im Dokument stehen. Sie werden nur auf dem Weg zum KI-Modell maskiert und vor der Rückgabe wiederhergestellt.
_field_blocks
Wo jeder Wert gefunden wurde. Schlüssel sind Feldpfade wie seller.name oder line_items[0].total; jeder Eintrag listet die Textzeilen mit Seite, Rahmen und Text. Ein Wert, der nicht zugeordnet werden konnte, fehlt hier. Wenn Sie nur die Daten brauchen, ignorieren Sie Schlüssel, die mit _ beginnen.
Koordinaten
- PDF und DOCX: PDF-Punkte (1/72 Zoll). Der Ursprung ist die linke untere Ecke der Seite;
yist die Oberkante des Rahmens, von unten gemessen. - Bilder: Pixel. Der Ursprung ist die linke obere Ecke;
yist die Oberkante, von oben gemessen.
{
"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"
}
]
}
}
}Dokumente
Die Dokumente des Projekts aus allen Quellen: Dashboard, API und E-Mail.
Dokumente auflisten
/api/v1/documentsNeueste zuerst. Aufgelistet werden nur gespeicherte Dokumente: API-Uploads erscheinen nur, wenn das Projekt sie speichert.
pageintegeroptional- Seitennummer, ab 1.
pageSizeintegeroptional- 1 bis 100; Standard 20.
statusstringoptionalPending,Processing,CompletedoderFailed.categorystringoptional- Name der Kategorie.
searchstringoptional- Teil des Dateinamens.
fileTypestringoptionalpdf,docxoderimage.sourcestringoptionaldashboard,apioderemail.processingModestringoptionalauto-classify,specific,auto-entityoderclassify-only.
Dokument abrufen
/api/v1/documents/{id}Das Dokument mit seinem Ergebnis. outputDeanonymized sind die extrahierten Daten, dasselbe Objekt wie extracted. Ein classify-only-Dokument hat seine Kategorie in categoryName und kein outputDeanonymized. Ein fehlgeschlagenes Dokument hat errorCode und errorMessage. Speichert das Projekt keine API-Uploads, ist der Status abrufbar, das Ergebnis aber nicht.
Dokument erneut verarbeiten
/api/v1/documents/{id}/reprocessFührt die Extraktion erneut aus, etwa nachdem Sie die Felder der Kategorie geändert haben. Optionaler JSON-Inhalt: category (ein Name oder auto) und processingMode. Antwortet mit 202; das Ergebnis kommt wie bei einem asynchronen Upload. Credits werden erneut berechnet. Ein classify-only-Dokument wird erneut klassifiziert (1 Credit), sofern Sie keine Kategorie nennen. Nicht möglich für API-Uploads, deren Dateien nicht gespeichert wurden (document.files_not_retained).
Klassifiziertes Dokument extrahieren
/api/v1/documents/{id}/extractFür ein mit classify-only hochgeladenes Dokument: extrahiert seine Felder als die gewählte Kategorie oder als die category im optionalen JSON-Inhalt. Kostet die Seiten des Dokuments abzüglich des Credits für die Klassifizierung. Antwortet mit 202; das Ergebnis kommt wie bei einem asynchronen Upload, als extraction.completed. Für jedes andere Dokument antwortet es mit 400 und document.not_classify_only; nutzen Sie dort die erneute Verarbeitung.
Dokument löschen
/api/v1/documents/{id}Löscht das Dokument, seine Datei und seine Ergebnisse. Antwortet mit 204.
Eine ID, die es im Projekt des Schlüssels nicht gibt, ergibt 404 mit document.not_found.
curl "https://parsevix.com/api/v1/documents?status=Completed&pageSize=20" \
-H "X-API-Key: $PARSEVIX_API_KEY"{
"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"{
"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 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 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 '{}'{
"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 -X DELETE https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581 \
-H "X-API-Key: $PARSEVIX_API_KEY"Kategorien
Die Kategorien des Projekts, einschließlich der eingebauten Vorlagen (isGlobal: true). Kategorien werden im Dashboard angelegt und bearbeitet.
Kategorien auflisten
/api/v1/categoriesSchema einer Kategorie abrufen
/api/v1/categories/{name}Die Felder, die eine Kategorie extrahiert. fieldName ist der Schlüssel in extracted. fieldType ist string, number, date, boolean, object oder array; Objekte und Listen haben ihre Felder in children. Groß- und Kleinschreibung des Namens im Pfad spielt keine Rolle.
curl https://parsevix.com/api/v1/categories \
-H "X-API-Key: $PARSEVIX_API_KEY"[
{
"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 "https://parsevix.com/api/v1/categories/Supplier%20invoice" \
-H "X-API-Key: $PARSEVIX_API_KEY"{
"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": []
}
]
}
]
}Schlüssel und Credits
/api/v1/meDas Projekt des Schlüssels und das Credit-Guthaben des Kontos. Credits gehören zum Konto und werden von allen seinen Projekten geteilt; resetsOn ist der Beginn des nächsten Zeitraums. Bei einem jährlichen Tarif ist der Zeitraum das Abrechnungsjahr, und monthlyLimit enthält die Credits des ganzen Jahres.
curl https://parsevix.com/api/v1/me \
-H "X-API-Key: $PARSEVIX_API_KEY"{
"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 verwalten
Webhooks lassen sich im Dashboard (Webhooks) oder über diese Endpunkte verwalten.
Webhook anlegen
/api/v1/webhooksurlstringPflicht- Eine öffentliche
https-URL. Adressen in privaten Netzen werden abgelehnt. eventsstring[]Pflicht- Eines oder mehrere von
extraction.completed,extraction.failedundclassification.completed. filtersobjectoptional- Optional.
sources(dashboard,api,email) undcategories(Namen) begrenzen, welche Dokumente Ereignisse senden.
Die Antwort enthält das Signatur-secret einmalig. Speichern Sie es, um Signaturen zu prüfen.
Webhooks auflisten
/api/v1/webhooksWebhook löschen
/api/v1/webhooks/{id}Beispielereignisse
/api/v1/webhooks/samplesDie neuesten Dokumente des Projekts als Ereignisinhalte, zum Testen Ihres Empfängers. Parameter: event (Pflicht), limit (1–10, Standard 3), category. Gibt es noch kein passendes Dokument, wird ein Beispiel aus dem Kategorie-Schema erzeugt.
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"] }
}'{
"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 "https://parsevix.com/api/v1/webhooks/samples?event=extraction.completed&limit=1" \
-H "X-API-Key: $PARSEVIX_API_KEY"Webhooks
Ist ein Dokument fertig, sendet Parsevix einen POST mit JSON-Inhalt an jeden Webhook des Projekts. Webhooks erhalten Dokumente aus allen Quellen: Dashboard, API und E-Mail.
Ereignisse
| Ereignis | Beschreibung |
|---|---|
| extraction.completed | Ein Dokument wurde verarbeitet. data enthält die extrahierten Felder. |
| classification.completed | Ein classify-only-Dokument hat seine Kategorie: document.category, die Seiten des Dokuments in document.page_count. Es gibt kein data. |
| extraction.failed | Ein Dokument konnte nicht verarbeitet werden, auch ein classify-only-Dokument. error_code ist einer der Fehlergründe; error ist die Meldung aus dem Dashboard. |
| test.ping | Wird über die Schaltfläche Test auf der Seite eines Webhooks im Dashboard gesendet. |
Header
| Header | Beschreibung |
|---|---|
| X-Webhook-Id | Ereignis-ID. Bei jedem Versuch gleich; damit erkennen Sie Duplikate. Auch das id im Inhalt. |
| X-Webhook-Event | Der Name des Ereignisses. |
| X-Webhook-Timestamp | Unix-Zeit dieses Versuchs, in Sekunden. |
| X-Webhook-Signature | sha256= gefolgt vom hexadezimalen HMAC-SHA256 über {timestamp}.{roher Inhalt}, mit dem Secret des Webhooks als Schlüssel. |
| X-Webhook-Attempt | Nummer des Versuchs, ab 1. |
Signatur prüfen
Berechnen Sie den HMAC über den rohen Inhalt der Anfrage, genau wie empfangen und vor dem Parsen. Lehnen Sie Ereignisse ab, deren Zeitstempel älter als 5 Minuten ist.
Antworten
- Antworten Sie innerhalb von 10 Sekunden mit einem
2xx-Status und verarbeiten Sie das Ereignis danach. Alles andere gilt als Fehlschlag. Weiterleitungen werden nicht verfolgt. - Fehlgeschlagene Zustellungen werden nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden und 24 Stunden wiederholt: 7 Versuche in etwa 33 Stunden.
- Die Antwort
410 Goneschaltet den Webhook sofort ab. Er wird auch abgeschaltet, wenn bei drei Ereignissen alle Versuche fehlgeschlagen sind und 3 Tage lang keine Zustellung gelungen ist. Der Inhaber erhält eine E-Mail; im Dashboard lässt er sich wieder einschalten. Ereignisse dazwischen werden nicht erneut gesendet. - Das Secret lässt sich im Dashboard erneuern. Das alte Secret ist sofort ungültig.
{
"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"
}
]
}
}
}{
"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
}
}{
"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 # älter als 5 Minuten: möglicherweise wiederholt
expected = hmac.new(
secret.encode(),
timestamp.encode() + b"." + raw_body,
hashlib.sha256,
).hexdigest()
return hmac.compare_digest(signature, "sha256=" + expected)Zapier
Die Parsevix-App für Zapier verbindet sich mit einem API-Schlüssel eines Projekts. Fügen Sie sie über den Einladungslink auf der Seite Zapier des Projekts im Dashboard oder hier hinzu.
Auslöser
- Extraction Completed: Ein Dokument wurde verarbeitet. Optional nur eine Kategorie oder Quelle.
- Extraction Failed: Ein Dokument konnte nicht verarbeitet werden.
- Document Classified: Ein nur zum Klassifizieren gesendetes Dokument hat seine Kategorie, etwa von einer E-Mail-Adresse, die nur klassifiziert.
Aktionen
- Extract Document sendet eine Datei aus einem vorherigen Schritt, optional mit einer Kategorie, und gibt die extrahierten Felder an die nächsten Schritte weiter. Mit gewählter Kategorie lassen sich ihre Felder schon beim Bau des Zaps zuordnen.
- Classify Document sendet eine Datei und gibt die von Parsevix gewählte Kategorie an die nächsten Schritte weiter, ohne Felder zu extrahieren. Damit verteilen Sie Dokumente nach Art.
Eingeschaltete Zaps erscheinen auf der Seite Zapier des Projekts und unter Webhooks.
Ab dem Starter-Tarif hat jedes Projekt unter E-Mail-Eingang eine E-Mail-Adresse. Jeder Anhang einer Mail an diese Adresse wird zu einem Dokument; die Ergebnisse erscheinen im Dashboard und gehen mit der Quelle email an Ihre Webhooks.
Adressen haben die Form name+inbox@inbox.parsevix.com. Je nach Tarif kann ein Projekt mehrere haben, zum Beispiel eine pro Lieferant oder Abteilung.
Je Adresse
- Anhänge: jeden Anhang als eine feste Kategorie extrahieren; Parsevix die Kategorie wählen lassen und dann extrahieren; oder nur die Kategorie wählen (
classify-only, 1 Credit pro Dokument), mit den Feldern später extrahiert, wenn Sie sie brauchen. - Erlaubte Absender: Nur Mails von diesen Domains werden angenommen, und nur wenn sie DKIM oder SPF für diese Domain bestehen; ein gefälschter Absender wird abgelehnt.
Was verarbeitet wird
- Anhänge als PDF, DOCX, PNG, JPEG und TIFF, auch in weitergeleiteten Mails. Bilder im Mailtext, etwa Logos in Signaturen, werden übersprungen.
- Eine Mail darf bis zu 30 MB groß sein; ihre ersten 20 Anhänge werden zu Dokumenten. Eine Adresse nimmt in 24 Stunden bis zu 1.000 Mails an und erzeugt bis zu 1.000 Dokumente; darüber hinaus werden Mails abgelehnt und Anhänge als nicht importiert aufgeführt. Der Empfang ist kostenlos; jedes Dokument kostet Credits wie jedes andere.
- Dieselbe Mail, zweimal zugestellt (gleiche Message-ID), wird einmal verarbeitet.
Fehler
Fehler haben einen HTTP-Status und einen Inhalt mit einem festen code und einer lesbaren message. Werten Sie code aus; Meldungstexte können sich ändern.
Statuscodes
| Status | Bedeutung |
|---|---|
| 400 | Die Anfrage ist ungültig: ein fehlender oder falscher Parameter, eine nicht unterstützte Datei, zu wenige Credits. validation.failed listet die Probleme je Parameter in fields. |
| 401 | Kein API-Schlüssel oder kein gültiger. |
| 403 | Der Schlüssel ist gültig, darf aber nicht verwendet werden. Siehe Authentifizierung. |
| 404 | Das Dokument, die Kategorie, der Webhook oder der Endpunkt existiert in diesem Projekt nicht. |
| 413 | Der Upload ist größer als die Grenze für Anfragen. |
| 422 | POST /extract oder POST /classify lief, aber das Dokument konnte nicht verarbeitet werden. |
| 429 | Anfrage- oder Gleichzeitigkeitsgrenze erreicht. Warten Sie Retry-After Sekunden. |
| 5xx | Ein Serverfehler (mit einer Referenz für den Support), Wartung (503) oder eine Zeitüberschreitung (504). |
Häufige Codes
| Code | Bedeutung |
|---|---|
| validation.file_required | Es wurde keine file gesendet. |
| document.content_not_supported | Der Inhalt der Datei ist kein PDF, DOCX, PNG, JPEG oder TIFF, egal was der Name sagt. |
| credit.file_size_exceeds_plan | Die Datei ist größer, als der Tarif erlaubt. |
| validation.language_invalid | language ist kein zweistelliger Code. |
| document.callback_url_* | callbackUrl ist keine öffentliche https-URL mit höchstens 2.000 Zeichen. |
| credit.insufficient_credits | In diesem Zeitraum sind nicht mehr genug Credits übrig. |
| document.refund_pending | Eine Erstattung des Abonnements wird geprüft; bis zu ihrem Abschluss wird nichts verarbeitet. |
| category.not_found | Im Projekt gibt es keine Kategorie mit diesem Namen. |
| document.classify_only_category | classify-only wurde zusammen mit einer Kategorie gesendet. Die Kategorie wählt diese Art selbst. |
| document.not_classify_only | POST /documents/{id}/extract wurde für ein Dokument aufgerufen, das nicht mit classify-only hochgeladen wurde. |
| document.files_not_retained | Die Dateien des API-Uploads wurden nicht gespeichert; er kann nicht erneut verarbeitet werden. |
| webhook.url_* | Die Webhook-URL ist keine öffentliche https-URL. |
| *.limit_reached | Eine Tarifgrenze wurde erreicht, etwa die Zahl der Webhooks pro Projekt. |
Fehlergründe
Warum ein Dokument fehlschlug: reason in der 422-Antwort von POST /extract oder POST /classify, error_code in extraction.failed, errorCode am Dokument.
| Code | Bedeutung |
|---|---|
| too_many_pages | Mehr als 30 Seiten. Teilen Sie die Datei. |
| sync_too_many_pages | Mehr Seiten, als POST /extract und POST /classify annehmen. |
| pdf_encrypted | Das PDF ist passwortgeschützt. |
| file_unreadable | Die Datei ist beschädigt oder kein gültiges Dokument. |
| no_text | Kein Text gefunden: leer, oder der Scan ist unlesbar. |
| no_categories | Die Kategorie sollte automatisch gewählt werden, aber das Projekt hat keine Kategorien. |
| no_schema_fields | Die Kategorie hat keine Felder. |
| no_fields_found | Keines der Felder der Kategorie wurde im Dokument gefunden; es ist wahrscheinlich falsch kategorisiert. Mit der richtigen Kategorie erneut verarbeiten. |
| no_data_found | Die automatische Extraktion hat im Dokument keine Daten gefunden. |
| insufficient_credits | Das Dokument braucht mehr Credits, als in diesem Zeitraum übrig sind. Es wurde nichts berechnet; verarbeiten Sie es nach einem Upgrade oder dem Zurücksetzen erneut. |
| refund_pending | Eine Erstattung des Abonnements wurde geprüft. Wird sie abgelehnt, verarbeiten Sie das Dokument erneut. |
| masking_failed | Personenbezogene Daten konnten nicht maskiert werden, daher ging das Dokument nicht an das KI-Modell. Erneut versuchen. |
| worker_unavailable | Die Verarbeitung war vorübergehend nicht verfügbar. Erneut versuchen. |
| ai_failed | Das KI-Modell ist vorübergehend ausgefallen. Erneut versuchen. |
| processing_failed | Ein interner Fehler. Erneut versuchen; bei Wiederholung den Support kontaktieren. |
| processing_timeout | Die Verarbeitung wurde vor dem Ende abgebrochen (etwa bei einem Neustart). Erneut versuchen. |
Die letzten fünf sind vorübergehend: Verarbeiten Sie das Dokument erneut oder senden Sie es noch einmal. Fehlgeschlagene Läufe werden nicht pro Seite berechnet.
{
"error": {
"code": "validation.failed",
"message": "The file field is required.",
"fields": {
"file": [
"The file field is required."
]
}
}
}{
"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"
}
}Grenzen und Credits
Dateien
- PDF, DOCX, PNG, JPEG und TIFF (auch mehrseitig). Der Typ wird aus dem Inhalt der Datei bestimmt, nicht aus dem Namen.
- Bis 10 MB und 30 Seiten pro Dokument.
Credits
- Jede verarbeitete Seite kostet 1 Credit. Die automatische Wahl der Kategorie kostet nichts extra.
- Nur klassifizieren (
classify-only) kostet 1 Credit pro Dokument. Ein solches Dokument später zu extrahieren kostet seine Seiten abzüglich dieses Credits; insgesamt bleibt es bei 1 Credit pro Seite. - Ein fehlgeschlagener Lauf kostet für seine Seiten nichts. Erneutes Verarbeiten kostet erneut Credits. Der Empfang von E-Mails ist kostenlos.
- Sind die Credits eines Zeitraums verbraucht, werden Uploads mit
credit.insufficient_creditsabgelehnt, bis zum nächsten Zeitraum oder einem Upgrade. Die Credits eines Dokuments werden reserviert, sobald seine Seiten gezählt sind; reichen sie dann nicht mehr, etwa nach vielen parallelen Uploads, schlägt das Dokument mitinsufficient_creditsfehl, und es wird nichts berechnet.
Anfragerate
Jeder API-Schlüssel darf je nach Tarif eine bestimmte Zahl von Anfragen pro Minute stellen. Jede Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (Unix-Zeit). Darüber erhalten Sie 429 mit Retry-After.
Nach Tarif
| Tarif | Anfragen / Minute | Credits / Monat | API-Schlüssel | Webhooks / Projekt |
|---|---|---|---|---|
| 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 | unbegrenzt | 25 |
Außerdem: POST /extract und POST /classify warten höchstens 285 Sekunden und erlauben zusammen 5 offene Anfragen pro Schlüssel.
{
"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
}
}Datenspeicherung
Was Parsevix von einem API-Upload speichert, ist eine Projekteinstellung: API-Uploads unter Projekteinstellungen. Standard ist Nach der Verarbeitung löschen; Wie Dashboard-Uploads speichern behält sie.
- Nach der Verarbeitung löschen: Die Datei wird am Ende der Verarbeitung gelöscht und das Ergebnis nicht gespeichert. Die API-Antwort, der Webhook oder der Callback ist die einzige Kopie. Solche Dokumente werden nicht aufgelistet und können weder erneut verarbeitet noch heruntergeladen werden;
retainedistfalse. - Wie Dashboard-Uploads speichern: Dateien und Ergebnisse werden wie Dashboard-Uploads gespeichert, bis Sie sie löschen.
Uploads über das Dashboard und per E-Mail werden immer gespeichert. Personenbezogene Daten werden maskiert, bevor Text das KI-Modell erreicht; siehe Sicherheit.
