Vorlagen & Felder

Eine Vorlage ist eine gespeicherte, wiederverwendbare Liste von Feldern, die aus einem Dokument extrahiert werden sollen – ein Feld pro Ausgabespalte. Übergeben Sie die id einer Vorlage an Starten der Batch-Verarbeitung, anstatt Ihre Felder bei jedem Aufruf erneut aufzulisten. Sie können eine Vorlage auch aus einem integrierten Preset erstellen oder Vorlagen ganz überspringen und Ad-hoc-fields direkt an process für einen einmaligen Durchlauf übergeben.

Vorlagen auflisten

Gibt Ihre gespeicherten Vorlagen zurück, jede mit ihrer vollständigen, geordneten Feldliste.

GET /api/v1/templates

Parameter

Name	Ort	Typ	Beschreibung
`limit`	Abfrage, optional	integer	1–100. Standard 50.
`page_token`	Abfrage, optional	string	Undurchsichtiger Cursor aus dem `next_page_token` einer vorherigen Antwort. Siehe Paginierung.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
invalid_parameter — ungültiger limit oder page_token.

Vorlage erstellen

Zwei Möglichkeiten, eine Vorlage in einem Endpoint zu erstellen: von Grund auf (optional durch Klonen der Felder einer anderen Vorlage über base_template_id) oder aus einer integrierten Vorlage über preset_id. Konten sind auf 30 Vorlagen begrenzt — löschen Sie eine vorhandene Vorlage, bevor Sie eine neue erstellen, sobald Sie das Limit erreicht haben.

POST /api/v1/templates

Parameter

Name	Ort	Typ	Beschreibung
`name`	body (JSON)	string	Erforderlich, sofern `preset_id` angegeben ist (in diesem Fall wird der Name der Vorlage selbst verwendet, bei Namenskonflikt mit einem Zeitstempel-Suffix ergänzt).
`preset_id`	body (JSON)	string, optional	Erstellt die Vorlage (und ihre Felder) aus einer integrierten Vorlage — gültige IDs finden Sie unter Vorlagen auflisten.
`base_template_id`	body (JSON)	integer, optional	Nur verwendet, wenn `preset_id` nicht angegeben ist — klont die Felder dieser vorhandenen Vorlage in die neue.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
missing_parameter (param: "name") — weder name noch preset_id angegeben.
invalid_parameter (param: "name") — eine Vorlage mit diesem Namen existiert bereits (nur bei Erstellung ohne Vorlage).
invalid_parameter (param: "preset_id") — unbekannte Vorlagen-ID.
template_limit_reached — das Limit von 30 Vorlagen für dieses Konto ist erreicht.
internal_error

Vorlageneinstellungen aktualisieren

Legt die globale Formatanforderung einer Vorlage fest (angewendet auf jede einzelne Feldanforderung) sowie deren Multi-Page-Merge-Konfiguration — ob mehrere hochgeladene Seiten, die zum selben logischen Datensatz gehören (ein mehrseitiger Mietvertrag, ein getackerter Belegstapel), zu einer einzigen Ausgabezeile zusammengeführt werden sollen, statt eine Zeile pro Seite zu bleiben. Sobald hier aktiviert, wird der Merge automatisch überall dort angewendet, wo diese Vorlage für Verarbeitung und Ergebnisse verwendet wird — siehe ?merge=true bei Get batch results und Export a batch (dort wird er immer angewendet, kein Opt-in erforderlich). Jedes Feld im Anfragetext unten ist optional; nur die Schlüssel, die Sie senden, werden aktualisiert, alles andere bleibt unverändert (es gibt keinen separaten Entwurfs-/Vorschauzustand zur Bestätigung — dieser Aufruf wirkt sofort, genau wie der Dialog „Vorlageneinstellungen" in der Web-App).

PUT /api/v1/templates/{id}/settings

Parameter

Name	Speicherort	Typ	Beschreibung
`id`	Pfad	integer	Die zu aktualisierende Vorlage.
`global_format_requirement`	Body (JSON), optional	string	Zusätzliche Anweisungen, die zusätzlich zu den eigenen `format_requirement`-Angaben jedes Felds angewendet werden.
`merge_enabled`	Body (JSON), optional	boolean	Aktiviert/deaktiviert Multi-Page Merge. Alle `merge_*`-Felder unten sind bedeutungslos, solange dies `false` ist.
`merge_mode`	Body (JSON), optional	string oder null	`"sequential"` (neuer Datensatz, wenn sich der Wert einer Datenspalte ändert), `"key_match"` (Gruppierung nach übereinstimmendem Datenspaltenwert unabhängig von der Upload-Reihenfolge) oder `"fixed_count"` (Gruppierung alle N Uploads).
`merge_field_name`	Body (JSON), optional	string oder null	Die Datenspalte (Feldname), die von den wertbasierten Auslösern von `sequential` und vom Gruppierungsschlüssel von `key_match` verwendet wird.
`merge_trigger_type`	Body (JSON), optional	string oder null	Nur für `sequential`: `"value_change"`, `"blank"`, `"has_value"` oder `"equals_value"`.
`merge_trigger_value`	Body (JSON), optional	string oder null	Nur für `merge_trigger_type: "equals_value"` — der Text oder Regex, der abgeglichen werden soll.
`merge_fixed_count`	Body (JSON), optional	integer oder null	Nur für `merge_mode: "fixed_count"` — Gruppengröße, mindestens 1.
`merge_conflict_policy`	Body (JSON), optional	string oder null	Wenn gruppierte Seiten beim Wert eines Felds abweichen: `"split"` (eine Ausgabezeile pro Seite statt Zusammenführung), `"first"`, `"last"` oder `"concat"` (Standard).
`merge_conflict_separator`	Body (JSON), optional	string oder null	Wird verwendet, wenn `merge_conflict_policy: "concat"`, maximal 20 Zeichen. `null` fällt auf das Standard-`" / "` zurück; `""` ist eine bewusste Wahl für „kein Trennzeichen" und wird unverändert gespeichert.
`merge_skip_preview`	Body (JSON), optional	boolean	Nur für Web-Apps relevant (steuert den Bestätigungsbildschirm der Exportvorschau) — hat keine Auswirkung auf das API-Verhalten, da die API keinen interaktiven Vorschauschritt zum Überspringen hat. Hier festlegbar, damit die vollständige Konfiguration einer Vorlage über diesen einen Endpunkt hin- und zurückübertragen werden kann.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
template_not_found
invalid_parameter — ungültiger merge_mode / merge_trigger_type / merge_fixed_count / merge_conflict_policy / merge_conflict_separator.
internal_error

Vorlage löschen

Löscht eine Vorlage und alle ihre Felder (kaskadierend — kein separater Cleanup-Aufruf nötig). Betrifft nicht Dokumente, die diese Vorlage bereits in einem früheren process-Aufruf verwendet haben; deren bereits extrahierte Ergebnisse bleiben unverändert.

DELETE /api/v1/templates/{id}

Parameter

Name	Ort	Typ	Beschreibung
`id`	Pfad	integer	Die zu löschende Vorlage.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
template_not_found
internal_error

Presets auflisten

Integrierte Feldlisten für gängige Dokumenttypen (Rechnungen, Belege, Kontoauszüge und mehr) — übergebe die id eines Presets als preset_id an Vorlage erstellen, um eine funktionsfähige Vorlage zu erhalten, ohne Felder selbst aufzulisten. Presets sind statische Konfiguration, keine Datenbankzeilen — es gibt keine Möglichkeit, eines über die API zu erstellen, zu bearbeiten oder zu löschen.

GET /api/v1/presets

Parameter

Name	Ort	Typ	Beschreibung
`category`	query, optional	string	Filter auf eine Kategorie (z. B. `"Finance & Accounting"`). Ohne Angabe werden alle Kategorien aufgelistet.
`limit`	query, optional	integer	1–100. Standard 50.
`page_token`	query, optional	string	Undurchsichtiger Cursor aus dem `next_page_token` einer vorherigen Antwort.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
invalid_parameter — ungültiges limit oder page_token.

Felder auflisten und erstellen

fields ist der v1-öffentliche Name für das, was die Produkt-UI als „Match-Regeln" bezeichnet — ein Feld pro Ausgabespalte, in der Reihenfolge, in der die Extraktion sie ausgibt. GET gibt jedes Feld der Vorlage zurück, bereits nach sort_order sortiert. POST fügt am Ende ein neues Feld hinzu.

GET POST /api/v1/templates/{id}/fields

Parameter

Name	Ort	Typ	Beschreibung
`id`	path	integer	Die Vorlage, zu der diese Felder gehören.
`name`	body (JSON), nur POST	string	Erforderlich. Muss innerhalb dieser Vorlage eindeutig sein — siehe Fehler unten.
`format_requirement`	body (JSON), nur POST	string, optional	Freitext-Hinweis zum erwarteten Wertformat (z. B. `"YYYY-MM-DD"`, `"Number"`).

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
template_not_found
missing_parameter (param: "name") — nur POST.
duplicate_field_name — ein Feld mit diesem name existiert bereits auf dieser Vorlage.
internal_error

Feld aktualisieren und löschen

PUT benennt ein Feld um (und ersetzt dessen format_requirement) — es ist ein vollständiger Ersatz, kein partielles Update, also beide Werte angeben, auch wenn sich nur einer geändert hat. DELETE entfernt es.

PUT DELETE /api/v1/templates/{id}/fields/{field_id}

Parameter

Name	Ort	Typ	Beschreibung
`id`	Pfad	integer	Die Vorlage, zu der dieses Feld gehört.
`field_id`	Pfad	integer	Das zu aktualisierende oder zu löschende Feld.
`name`	Body (JSON), nur PUT	string	Erforderlich. Neuer Name.
`format_requirement`	Body (JSON), nur PUT	string, optional	Neuer Format-Hinweis — weglassen und er wird auf einen leeren String gesetzt, nicht unverändert gelassen.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
template_not_found — die Vorlage existiert nicht/gehört nicht Ihnen, oder (mit einer entsprechenden Meldung) die field_id ist nicht auf dieser Vorlage.
missing_parameter (param: "name") — nur PUT.
duplicate_field_name — nur PUT, beim Umbenennen auf einen Namen, den bereits ein anderes Feld auf dieser Vorlage hat.
internal_error

Felder neu anordnen

Legt die Feldreihenfolge explizit fest, die die Spaltenreihenfolge in line_items und in Excel/Word-Exporten bestimmt. IDs in der Liste, die nicht zu dieser Vorlage gehören, werden stillschweigend ignoriert, anstatt die gesamte Anfrage abzulehnen.

PATCH /api/v1/templates/{id}/fields/order

Parameter

Name	Ort	Typ	Beschreibung
`id`	Pfad	integer	Die Vorlage, die neu angeordnet werden soll.
`field_ids`	Body (JSON)	Array von Integers	Jede Feld-ID dieser Vorlage, in der gewünschten Reihenfolge. Erforderlich.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
template_not_found
invalid_parameter (param: "field_ids") — keine Liste von Integers.
internal_error

Code	HTTP Status	Description
validation_error	422	Invalid field data
not_found	404	Field or template not found
unauthorized	401	Invalid or missing API key
rate_limited	429	Too many requests

Erste Schritte

Anleitungen

API-Referenz

Mehr

Vorlagen & Felder

Vorlagen auflisten

Parameter

Mögliche Fehler

Vorlage erstellen

Parameter

Mögliche Fehler

Vorlageneinstellungen aktualisieren

Parameter

Mögliche Fehler

Vorlage löschen

Parameter

Mögliche Fehler

Presets auflisten

Parameter

Mögliche Fehler

Felder auflisten und erstellen

Parameter

Mögliche Fehler

Feld aktualisieren und löschen

Parameter

Mögliche Fehler

Felder neu anordnen

Parameter

Mögliche Fehler