> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Document AI API: Individuelle Datenextraktion > Didit: POST /v3/document-ai/ extrahiert eigene Felder aus PDFs und Bildern, mit Namensabgleich und Manipulationsprüfung. $0.20 pro Dokument. Senden Sie ein Dokument zusammen mit der Liste der Felder, die daraus gelesen werden sollen. Didit wendet sein Standard-Extraktionsmodell auf die Datei an, gibt jedes Feld typisiert zurück (`text`, `number` oder `date` als `YYYY-MM-DD`), erkennt und dekodiert unterstützte QR-Codes und Barcodes, prüft die Datei auf Manipulationen und vergleicht optional den Namen auf dem Dokument mit der erwarteten Person oder dem erwarteten Unternehmen. Verwenden Sie dies für Kapitalnachweise, Gehaltsabrechnungen, Kontoauszüge, Steuerdokumente, Rechnungen oder jedes Dokument, das keiner festen Vorlage entspricht. Dies ist die Server-zu-Server-Version des gehosteten [Document AI](https://docs.didit.me/de/core-technology/document-ai/overview.md)-Schritts. Die Anfrage ist `multipart/form-data`: Die Datei wird im Feld `document` übergeben, die Felddefinitionen im Feld `fields` als eine JSON-kodierte Zeichenfolge mit einem Array. ## Felder zur Extraktion definieren `fields` ist ein JSON-Array mit 1 bis 30 Elementen, das als einzelner String gesendet wird. Jedes Element hat einen `key` (Kleinbuchstaben, Ziffern und Unterstriche, innerhalb der Anfrage eindeutig), einen menschenlesbaren `name`, eine `instruction`, die dem Modell sagt, wonach es suchen soll, einen `type` (`text`, `number` oder `date`) sowie zwei Flags: `required` und `is_full_name`. ```json theme={null} [ { "key": "account_holder", "name": "Account holder", "instruction": "Full name of the person or company the account belongs to", "type": "text", "required": true, "is_full_name": true }, { "key": "balance", "name": "Closing balance", "instruction": "Closing balance shown on the statement, as a number without the currency symbol", "type": "number", "required": true }, { "key": "currency", "name": "Currency", "instruction": "Three-letter currency code of the balance", "type": "text" }, { "key": "statement_date", "name": "Statement date", "instruction": "Date the statement was issued", "type": "date", "required": true } ] ``` Bei einer Multipart-Anfrage ist das gesamte Array ein einziger Formularwert: ```bash theme={null} curl -X POST https://verification.didit.me/v3/document-ai/ \ -H "x-api-key: $DIDIT_API_KEY" \ -F "document=@./bank-statement.pdf" \ -F 'fields=[{"key":"account_holder","name":"Account holder","instruction":"Full name of the account holder","type":"text","required":true,"is_full_name":true},{"key":"balance","name":"Closing balance","instruction":"Closing balance as a number","type":"number","required":true}]' \ -F "expected_first_name=Jane" \ -F "expected_last_name=Doe" ``` Die Antwort gibt die normalisierten `fields` zurück und liefert `extracted_data`, geschlüsselt nach Ihren `key`-Werten, mit `null` für alles, was das Modell nicht finden konnte. `name`, `instruction` und `type` sind bei jedem Element optional (`type` ist standardmäßig `text`); `key` ist erforderlich. Wenn Sie `fields` als Formularschlüssel im Klammerformat (`fields[0][key]=...`) senden oder als etwas anderes als ein JSON-Array, gibt die Anfrage `400` zurück, bevor eine Extraktion läuft, sodass nichts abgerechnet wird. ## QR-Codes und Barcodes Jede erfolgreiche Antwort enthält `document_ai.detected_codes`. Jedes Element enthält: | Feld | Beschreibung | | - | - | | `type` | Erkannte Symbologie, etwa `QR_CODE`, `CODE_128`, `EAN_13`, `DATA_MATRIX` oder `PDF_417` | | `page_number` | Seitennummer, beginnend bei 1 | | `position` | Erkanntes Polygon in Pixeln der gerenderten Seite oder `null`, wenn keine verlässliche Position verfügbar ist | | `x`, `y`, `width`, `height` | Begrenzungsrahmen in Pixeln der gerenderten Seite oder `null`, wenn keine verlässliche Position verfügbar ist | | `page_width`, `page_height` | Abmessungen der gerenderten Seite, auf die sich die Koordinaten beziehen | | `parsed_payload` | Dekodierter String oder strukturierter Wert oder `null`, wenn der Code nur lokalisiert werden kann | | `raw_payload` | Roher Decoder-Payload als Base64-String, sofern verfügbar; andernfalls ein leerer String | Das Array umfasst jede verarbeitete Seite eines PDFs und ist leer, wenn kein unterstützter Code gefunden wird. Didit errät niemals einen Payload: Beschädigte QR-Codes können mit ihrer Position und `parsed_payload: null` zurückgegeben werden, und Fehler bei der Codeerkennung lassen die Document-AI-Anfrage nicht fehlschlagen. ## Namensabgleich Markieren Sie höchstens ein Feld mit `is_full_name: true` und senden Sie, wem das Dokument Ihrer Erwartung nach gehört: | Sie prüfen | Senden Sie | Der Name wird verglichen mit | | - | - | - | | Eine Person | `expected_first_name` + `expected_last_name` | dem vollständigen Namen der Person | | Ein Unternehmen | `expected_company_name` (+ optional `expected_company_country`, ein zweibuchstabiger ISO-Code) | dem Unternehmensnamen | Senden Sie entweder die eine oder die andere Gruppe, nicht beide. Wenn ein Name extrahiert wird und ein erwarteter Name vorhanden ist, enthält die Antwort `name_match_score` (0 bis 100) und `name_on_document`. Liegt der Wert unter `document_ai_name_match_score_threshold` (Standard `80`), löst dies die Warnung `DOCUMENT_AI_NAME_MISMATCH` aus und wendet `document_ai_name_mismatch_action` an. Wenn kein Feld als `is_full_name` markiert ist, greift Didit auf das erste Textfeld zurück, dessen Schlüssel nach einem Namen aussieht (`name`, `holder`, `full_name`, `account_holder`). Markieren Sie das Feld ausdrücklich, wenn Sie steuern möchten, welcher Wert verglichen wird. Wenn auf dem Dokument kein Namenswert gefunden wird oder kein erwarteter Name gesendet wird, entfällt die Namensprüfung und `name_match_score` ist `null`. ## Risiken und Aktionen Jedes der folgenden Risiken ist einem Aktionsparameter zugeordnet, den Sie pro Anfrage festlegen können: `DECLINE`, `REVIEW` oder `NO_ACTION`. Die strengste ausgelöste Aktion bestimmt `document_ai.status` (`Declined` > `In Review` > `Approved`), und jedes ausgelöste Risiko wird in `document_ai.warnings` aufgeführt. Die Standardwerte entsprechen dem gehosteten Workflow-Schritt. Wie jedes Risiko erkannt wird, erfahren Sie unter [Document AI-Regeln und Warnungen](https://docs.didit.me/de/core-technology/document-ai/warnings-document-ai.md). | Risiko | Parameter | Standard | | - | - | - | | `DOCUMENT_AI_UNREADABLE_DOCUMENT` | `document_ai_unreadable_document_action` | `REVIEW` | | `DOCUMENT_AI_MISSING_REQUIRED_FIELDS` | `document_ai_missing_required_fields_action` | `REVIEW` | | `DOCUMENT_AI_SUSPECTED_MANIPULATION` | `document_ai_document_tampering_action` | `DECLINE` | | `DOCUMENT_AI_NAME_MISMATCH` | `document_ai_name_mismatch_action` | `NO_ACTION` | | `DOCUMENT_AI_UNSUPPORTED_FILE` | `document_ai_unsupported_file_action` | `REVIEW` | ## Dateien, Speicherung und Abrechnung * **Akzeptierte Dateien:** PDF (mehrseitig unterstützt), JPG, JPEG, PNG, TIFF, WebP oder ein ZIP-Archiv mit dem Dokument, bis zu 30 MB. Verschlüsselte PDFs geben `400` zurück; laden Sie stattdessen ein entschlüsseltes PDF oder ein Foto hoch. * **`save_api_request`** (Standard `true`): Die Anfrage, die extrahierten Felder und die erkannten Codes erscheinen in der Business Console unter **Manuelle Prüfungen**, wo Ihr Team sie prüfen kann. Setzen Sie den Wert auf `false`, um das Speichern zu überspringen. * **`vendor_data`** und **`metadata`** werden unverändert in der Antwort zurückgegeben, damit Sie das Ergebnis mit Ihren eigenen Datensätzen verknüpfen können. * **Preis:** \$0.20 pro Dokument, abgerechnet, wenn das Dokument verarbeitet und ein Status zurückgegeben wird. Ihr Tarifrabatt gilt. Siehe [Preise](https://docs.didit.me/de/getting-started/pricing.md#preise-für-standalone-apis-server-zu-server). > [!NOTE] > > Soll der Nutzer das Dokument selbst hochladen, bis zu 3 Dokumente in einem Ablauf erfassen, den Upload-Bildschirm automatisch übersetzen lassen oder extrahierte Felder mit Ausweis- oder Fragebogendaten abgleichen? Verwenden Sie stattdessen den gehosteten [Document AI-Workflow-Schritt](https://docs.didit.me/de/core-technology/document-ai/overview.md). ## OpenAPI ````yaml de/openapi-25.json POST /v3/document-ai/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API für Ausweisverifizierung. Authentifizierung über den x-api-key-Header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/document-ai/: post: tags: - Standalone APIs summary: Document AI (benutzerdefinierte Feldextraktion + Manipulationsprüfungen) description: >- Extrahieren Sie die Felder, die **Sie** definieren, aus jedem beliebigen Beleg – Gehaltsabrechnungen, Kapitalnachweisen, Schreiben zur Vermögensherkunft, Steuerbescheinigungen, Verträgen, Rechnungen – in einem einzigen Aufruf. Senden Sie die Datei sowie eine `fields`-Definition (Key, Name, Extraktionsanweisung, Typ) und erhalten Sie typisierte Werte (`text`, `number`, `date` im Format `YYYY-MM-DD`), einen optionalen Übereinstimmungswert beim Namensabgleich mit der erwarteten Person oder dem erwarteten Unternehmen, PDF/EXIF-Manipulationssignale, einen `status` von `Approved`/`Declined`/`In Review` sowie eine `warnings`-Liste zurück, die jedes gefundene Problem erläutert. Dies ist das Server-zu-Server-Gegenstück zum gehosteten Document AI-Workflow-Schritt (siehe `/core-technology/document-ai/overview`); es verwendet Didits Standard-Extraktionsmodell und bietet keine Anbieterauswahl. **Latenz.** Die Extraktion ist LLM-basiert: Typische Aufrufe dauern **5–15 Sekunden**, mehrseitige PDFs bis zu **~30 Sekunden**. Konfigurieren Sie ein Client-Timeout von **mindestens 45 Sekunden** und führen Sie vor Abschluss des Aufrufs keinen Wiederholungsversuch durch. **Anfrageformat.** Nur `multipart/form-data`. `fields` ist **ein einzelner JSON-codierter Array-String** (1–30 Elemente, maximal 16 KB); Formular-Arrays in eckigen Klammern werden mit `400` abgewiesen. Jedes Element ist `{key, name, instruction, type, required, is_full_name}` – `key` ist der JSON-Schlüssel, den Sie zurückerhalten (`^[a-z0-9_]{1,64}$`, eindeutig), `instruction` teilt dem Modell mit, was gelesen werden soll, `type` ist `text` (Standard) | `number` | `date`, `required` löst `DOCUMENT_AI_MISSING_REQUIRED_FIELDS` aus, wenn der Wert nicht gelesen werden kann, und höchstens ein Feld darf `is_full_name: true` setzen, um den Wert zu markieren, der mit dem erwarteten Namen verglichen wird. **Namensabgleich.** Übergeben Sie `expected_first_name` + `expected_last_name` (Person) **oder** `expected_company_name` (+ optional `expected_company_country`) – nicht beides. Der Wert des Feldes `is_full_name` (oder, falls keines markiert ist, das erste Textfeld, dessen Schlüssel wie ein Name aussieht) wird per Fuzzy-Matching verglichen; `name_match_score` (0–100) und `name_on_document` werden immer zurückgegeben, wenn beide Seiten vorhanden sind, und ein Wert unter `document_ai_name_match_score_threshold` (Standard 80) fügt `DOCUMENT_AI_NAME_MISMATCH` hinzu, gesteuert durch `document_ai_name_mismatch_action`. **Entscheidungslogik.** Jedes Risiko wird einer konfigurierbaren Aktion zugeordnet: `DECLINE` → `status: "Declined"`, `REVIEW` → `status: "In Review"`, `NO_ACTION` → rein informativ. Die Standardwerte entsprechen dem Workflow-Schritt: unlesbares Dokument `REVIEW`, fehlende erforderliche Felder `REVIEW`, Manipulationsverdacht `DECLINE`, Namensabweichung `NO_ACTION`, nicht unterstützte Datei `REVIEW`. Ein Dokument, das überhaupt nicht verarbeitet werden kann, gibt `400` zurück; ein lesbares, aber problematisches Dokument gibt `200` mit `Declined`/`In Review` zurück – prüfen Sie immer `document_ai.status` und `document_ai.warnings`, nicht nur den HTTP-Code. **Abrechnung.** Jede `200`-Antwort verbraucht einen Document AI-API-Credit – **$0.20 pro Dokument** laut Preisliste, bezahlt aus Ihrem Tarifguthaben oder Ihrem Aufladeguthaben. Wenn das Guthaben der Organisation den Aufruf nicht decken kann, gibt der Endpoint vor jeglicher Verarbeitung `403` zurück. Sandbox-API-Schlüssel geben eine deterministische Mock-Antwort zurück und werden nicht berechnet. **Persistenz.** Mit `save_api_request=true` (Standard) wird der Aufruf als Sitzung vom Typ API gespeichert: Das Dokument, die extrahierten Werte, die Felddefinitionen und der Snapshot des Namensabgleichs werden aufbewahrt, die Sitzung wird in der Business Console angezeigt und `request_id` funktioniert mit `GET /v3/session/{sessionId}/decision/`. operationId: post_v3document-ai requestBody: required: true content: multipart/form-data: schema: type: object required: - document - fields properties: document: type: string format: binary description: >- Das zu lesende Dokument. Zulässige Dateiendungen: `tiff`, `jpg`, `jpeg`, `png`, `pdf`, `webp`, `zip`. Maximale Upload-Größe: **30 MB** (größere Dateien werden mit `400` abgelehnt). Mehrseitige PDFs werden unterstützt (rechnen Sie mit höherer Latenz); verschlüsselte PDFs werden mit `400` abgelehnt. Bilder werden vor der Verarbeitung automatisch komprimiert. fields: type: string description: >- Ein JSON-codierter Array-String mit **1–30** Felddefinitionen (maximal 16 KB). Jedes Element: `key` (erforderlich, `^[a-z0-9_]{1,64}$`, eindeutig – der in `extracted_data` zurückgegebene Schlüssel), `name` (≤100 Zeichen, in Nachrichten angezeigt), `instruction` (≤500 Zeichen, was das Modell lesen soll), `type` (`text` Standard | `number` | `date`), `required` (Boolean, Standard `false`), `is_full_name` (Boolean, Standard `false`, maximal eines pro Anfrage). Formular-Arrays in Klammerschreibweise, ungültiges JSON, doppelte Schlüssel oder mehr als ein `is_full_name` geben vor jeglicher Verarbeitung oder Abrechnung `400` zurück. example: >- [{"key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false}, {"key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true}, {"key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false}, {"key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false}] expected_first_name: type: string description: >- Vorname, der mit dem Namensfeld des Dokuments abgeglichen werden soll (Fuzzy-Match, transliterationssensitiv). Zusammen mit `expected_last_name` verwenden; kann nicht mit `expected_company_name` kombiniert werden. example: Sophia expected_last_name: type: string description: >- Mit dem Namensfeld des Dokuments abzugleichender Nachname, der zusammen mit `expected_first_name` für `name_match_score` herangezogen wird. example: Martinez expected_company_name: type: string description: >- Unternehmensname zum Abgleich mit dem Namensfeld des Dokuments (für Unternehmensdokumente). Kann nicht mit `expected_first_name` / `expected_last_name` kombiniert werden (absichtlich kein Beispielwert – das generierte Anfragebeispiel verwendet die Personenfelder; ersetzen Sie diese durch diesen Wert bei der Verifizierung eines Unternehmensdokuments). expected_company_country: type: string description: >- Optionaler ISO 3166-1 alpha-2 Ländercode (zwei ASCII-Buchstaben, z. B. `FR`), der die Normalisierung von Firmennamen für `expected_company_name` anpasst. Wird nur mit `expected_company_name` verwendet. document_ai_name_match_score_threshold: type: integer minimum: 0 maximum: 100 default: 80 description: >- Minimaler `name_match_score` (0–100), ab dem der Name als übereinstimmend gilt. Ein niedrigerer Wert fügt `DOCUMENT_AI_NAME_MISMATCH` hinzu, gesteuert durch `document_ai_name_mismatch_action`. example: 80 document_ai_unreadable_document_action: type: string enum: - DECLINE - REVIEW - NO_ACTION default: REVIEW description: >- Was zu tun ist, wenn kein Feld aus dem Dokument gelesen werden konnte (`DOCUMENT_AI_UNREADABLE_DOCUMENT`). document_ai_missing_required_fields_action: type: string enum: - DECLINE - REVIEW - NO_ACTION default: REVIEW description: >- Was zu tun ist, wenn mindestens ein `required`-Feld nicht gelesen werden konnte (`DOCUMENT_AI_MISSING_REQUIRED_FIELDS`; `additional_data.missing_fields` listet diese auf). document_ai_document_tampering_action: type: string enum: - DECLINE - REVIEW - NO_ACTION default: DECLINE description: >- Was zu tun ist, wenn die PDF-/EXIF-Forensik eine Manipulation vermutet — nach digitaler Signatur geändert, bekannter PDF-Editor, Overlay-Text-Manipulation, verdächtiger Re-Export, Bildanomalien (`DOCUMENT_AI_SUSPECTED_MANIPULATION`). document_ai_name_mismatch_action: type: string enum: - DECLINE - REVIEW - NO_ACTION default: NO_ACTION description: >- Was zu tun ist, wenn `name_match_score` unter dem Schwellenwert liegt (`DOCUMENT_AI_NAME_MISMATCH`). document_ai_unsupported_file_action: type: string enum: - DECLINE - REVIEW - NO_ACTION default: REVIEW description: >- Was zu tun ist, wenn der Upload leer oder keine verarbeitbare Datei ist (`DOCUMENT_AI_UNSUPPORTED_FILE`). save_api_request: type: boolean default: true description: >- Wenn `true` (Standard), wird der Aufruf als Sitzung vom Typ API persistent gespeichert — sichtbar in der Business Console, abrufbar über `GET /v3/session/{sessionId}/decision/` unter Verwendung der zurückgegebenen `request_id`, wobei das hochgeladene Dokument, die extrahierten Werte, die Felddefinitionen und der Namensabgleich-Snapshot gespeichert werden. Wenn `false`, wird nichts gespeichert und `request_id` ist eine flüchtige UUID, die nur der Antwortkorrelation dient; der Aufruf wird dennoch abgerechnet. example: true vendor_data: type: string description: >- Optionale opake Zeichenfolge (Ihre interne Benutzer-ID, E-Mail, UUID…), die in der gespeicherten Sitzung hinterlegt und in der Antwort zurückgegeben wird. Verwenden Sie sie, um API-Aufrufe mit Ihren eigenen Datensätzen abzugleichen und Sitzungen später zu filtern. example: user-123 metadata: type: object additionalProperties: true description: >- Optionales JSON-Objekt, das mit der Sitzung gespeichert (wenn `save_api_request=true`) und in der Antwort zurückgegeben wird. Senden Sie es bei Multipart-Anfragen als JSON-codiertes String-Feld (z. B. `metadata={"flow":"onboarding"}`) – es wird in ein Objekt geparst. example: flow: onboarding responses: '200': description: >- Dokument verarbeitet. `document_ai.status` ist `Approved`, `Declined` oder `In Review`; jedes erkannte Problem wird einzeln in `document_ai.warnings` aufgeführt. Ein problematisches Dokument gibt dennoch `200` zurück – prüfen Sie den Body, nicht nur den HTTP-Code. Wenn `save_api_request=true`, ist `request_id` die persistierte Sitzungs-ID. content: application/json: examples: Approved: summary: Gehaltsabrechnung fehlerfrei gelesen, Name stimmte überein value: request_id: 9d6a3b1e-2f0c-4a8e-9b7d-1c2e3f4a5b6c document_ai: status: Approved extracted_data: employer_name: Acme Payments Ltd employee_name: Sophia Martinez net_pay: 3120.5 pay_date: '2026-07-31' detected_codes: - type: CODE_128 page_number: 1 position: - - 96 - 456 - - 96 - 616 - - 1012 - 611 - - 1015 - 456 x: 96 'y': 456 width: 919 height: 160 page_width: 1200 page_height: 1700 raw_payload: SU5WLTIwMjYtMDA0Mg== parsed_payload: INV-2026-0042 fields: - key: employer_name name: Employer name instruction: The employer or company issuing the payslip. type: text required: true is_full_name: false - key: employee_name name: Employee name instruction: >- The full name of the employee as printed on the payslip. type: text required: true is_full_name: true - key: net_pay name: Net pay instruction: The net amount paid to the employee for the period. type: number required: true is_full_name: false - key: pay_date name: Pay date instruction: The payment date shown on the payslip. type: date required: false is_full_name: false name_match_score: 100 name_on_document: Sophia Martinez warnings: [] vendor_data: user-123 metadata: flow: onboarding created_at: '2026-08-19T16:40:12.318Z' In Review — missing required field: summary: '`net_pay` konnte nicht gelesen werden; Standardaktion REVIEW' value: request_id: 3f2a9c7b-5d4e-4b1a-8c6f-0e9d8c7b6a5f document_ai: status: In Review extracted_data: employer_name: Acme Payments Ltd employee_name: Sophia Martinez net_pay: null pay_date: '2026-07-31' detected_codes: [] fields: - key: employer_name name: Employer name instruction: The employer or company issuing the payslip. type: text required: true is_full_name: false - key: employee_name name: Employee name instruction: >- The full name of the employee as printed on the payslip. type: text required: true is_full_name: true - key: net_pay name: Net pay instruction: The net amount paid to the employee for the period. type: number required: true is_full_name: false - key: pay_date name: Pay date instruction: The payment date shown on the payslip. type: date required: false is_full_name: false name_match_score: 100 name_on_document: Sophia Martinez warnings: - risk: DOCUMENT_AI_MISSING_REQUIRED_FIELDS feature: DOCUMENT_AI additional_data: missing_fields: - Net pay log_type: warning short_description: Required fields could not be extracted long_description: >- One or more fields configured as required could not be extracted from the uploaded document. vendor_data: null metadata: null created_at: '2026-08-19T16:41:05.002Z' Declined — suspected manipulation: summary: >- PDF-Forensik hat einen bekannten Editor erkannt; Standardaktion DECLINE value: request_id: 7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f document_ai: status: Declined extracted_data: employer_name: Acme Payments Ltd employee_name: Sophia Martinez net_pay: 3120.5 pay_date: '2026-07-31' detected_codes: [] fields: - key: employer_name name: Employer name instruction: The employer or company issuing the payslip. type: text required: true is_full_name: false - key: employee_name name: Employee name instruction: >- The full name of the employee as printed on the payslip. type: text required: true is_full_name: true - key: net_pay name: Net pay instruction: The net amount paid to the employee for the period. type: number required: true is_full_name: false - key: pay_date name: Pay date instruction: The payment date shown on the payslip. type: date required: false is_full_name: false name_match_score: null name_on_document: Sophia Martinez warnings: - risk: DOCUMENT_AI_SUSPECTED_MANIPULATION feature: DOCUMENT_AI additional_data: detection_method: known_editor processed_by_known_editor: ilovepdf log_type: error short_description: Suspected document manipulation long_description: >- The system detected signs of potential manipulation or editing in the uploaded document. vendor_data: null metadata: null created_at: '2026-08-19T16:42:40.771Z' schema: type: object properties: request_id: type: string format: uuid description: >- Beibehaltene Sitzungs-ID, wenn `save_api_request=true` (verwendbar mit `GET /v3/session/{sessionId}/decision/`); andernfalls eine vorübergehende Korrelations-UUID. document_ai: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- `Approved`, wenn keine Warnung zu einer Ablehnung oder Prüfung führt; `Declined`, wenn mindestens ein Risiko `DECLINE` entspricht; andernfalls `In Review`, wenn mindestens eines `REVIEW` entspricht. Die Liste `warnings` erklärt warum. extracted_data: type: object additionalProperties: true description: >- Ein Eintrag pro angefordertem Feldschlüssel. Die Werte sind entsprechend dem `type` des Felds typisiert — Zeichenfolgen für `text`, Zahlen für `number`, `YYYY-MM-DD`-Zeichenfolgen für `date` — oder `null`, wenn der Wert nicht gelesen werden konnte. example: employer_name: Acme Payments Ltd employee_name: Sophia Martinez net_pay: 3120.5 pay_date: '2026-07-31' detected_codes: type: array description: >- Auf jeder verarbeiteten Seite erkannte QR-Codes und Barcodes. Leer, wenn keine gefunden wurden. Ein lokalisierter, aber nicht decodierbarer QR-Code weist `parsed_payload: null` auf. items: $ref: '#/components/schemas/DocumentAIDetectedCode' fields: type: array description: >- Die normalisierten Felddefinitionen, die für diese Extraktion verwendet wurden, als Echo zurückgegeben (auch mit der Sitzung gespeichert, wenn `save_api_request=true`). items: type: object properties: key: type: string name: type: string instruction: type: string type: type: string enum: - text - number - date required: type: boolean is_full_name: type: boolean name_match_score: type: number nullable: true minimum: 0 maximum: 100 description: >- Fuzzy-Ähnlichkeit (0–100) zwischen `name_on_document` und dem erwarteten Personen-/Unternehmensnamen. Wird zurückgegeben, sobald sowohl ein Namenswert als auch ein erwarteter Name existieren – bei Übereinstimmungen **und** Abweichungen; andernfalls `null`. example: 96 name_on_document: type: string nullable: true description: >- Der aus dem Dokument entnommene Namenswert (das Feld `is_full_name` oder das erste namensähnliche Textfeld), der mit dem erwarteten Namen verglichen wurde. `null`, wenn kein Namenswert verfügbar war. example: Sophia Martinez warnings: type: array description: >- Leer bei einer fehlerfreien Genehmigung. Jeder Eintrag erläutert ein erkanntes Risiko; Einträge mit `log_type: "error"` setzen `status` auf `Declined`, Einträge mit `log_type: "warning"` setzen ihn auf `In Review`. items: type: object properties: risk: type: string enum: - DOCUMENT_AI_UNREADABLE_DOCUMENT - DOCUMENT_AI_MISSING_REQUIRED_FIELDS - DOCUMENT_AI_SUSPECTED_MANIPULATION - DOCUMENT_AI_NAME_MISMATCH - DOCUMENT_AI_UNSUPPORTED_FILE description: >- Maschinenlesbarer Risiko-Code. Jeder Code wird durch die entsprechende `document_ai_*_action`-Anfrageoption gesteuert. example: DOCUMENT_AI_MISSING_REQUIRED_FIELDS feature: type: string enum: - DOCUMENT_AI description: >- Funktion, die die Warnung ausgelöst hat. An diesem Endpoint immer `DOCUMENT_AI`. additional_data: type: object nullable: true additionalProperties: true description: >- Zusätzlicher Kontext für das Risiko: `{"missing_fields": ["Net pay"]}` bei fehlenden Pflichtfeldern, `{"name_on_document", "score", "threshold"}` bei Namensabweichungen und der forensische Befund (`detection_method`, Ersteller-/Bearbeiter-Details) bei Manipulationsverdacht. `null`, wenn nichts hinzuzufügen ist. example: missing_fields: - Net pay log_type: type: string enum: - error - warning - information description: >- Schweregrad, der aus der konfigurierten Aktion abgeleitet wird: `error` (DECLINE), `warning` (REVIEW), `information` (NO_ACTION). short_description: type: string description: >- Für Menschen lesbare einzeilige Zusammenfassung des Risikos. example: Required fields could not be extracted long_description: type: string description: >- Lesbare Erklärung, gegebenenfalls mit `additional_data` interpoliert. vendor_data: type: string nullable: true description: >- Rückgabe der von Ihnen gesendeten `vendor_data` oder `null`. metadata: type: object nullable: true additionalProperties: true description: >- Rückgabe des von Ihnen gesendeten `metadata`-Objekts oder `null`. created_at: type: string format: date-time description: Wann die Anfrage verarbeitet wurde (UTC, ISO 8601). '400': description: >- Validierungs- oder Verarbeitungsfehler. Probleme auf Feldebene geben das Standard-Antwortformat von DRF zurück (ein Array von Meldungen pro betroffenem Feld). Verschlüsselte oder unlesbare Dokumente sowie Extraktionsfehler geben `{"error": ...}` zurück. content: application/json: examples: Missing document: summary: '`document` ist nicht in den Formulardaten enthalten' value: document: - No file was submitted. Invalid fields payload: summary: '`fields` ist kein einzelner JSON-codierter Array-String' value: fields: - fields must be a valid JSON array string. Duplicate field keys: summary: Zwei Elemente teilen denselben `key` value: fields: - Every fields item must have a unique key. Conflicting expectations: summary: Erwartungen für Person und Unternehmen gemeinsam gesendet value: non_field_errors: - >- Provide either person expected-name fields or expected_company_name, not both. Invalid metadata: summary: >- `metadata` ist kein JSON-Objekt (oder enthält ein NUL-Zeichen) value: metadata: - Metadata must be a JSON object. Oversized vendor_data: summary: '`vendor_data` überschreitet die Obergrenze von 2.000 Bytes' value: vendor_data: - vendor_data is too long (maximum 2000 bytes). Encrypted PDF: summary: Passwortgeschützte PDF-Datei value: error: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Extraction failed: summary: >- Die Extraktions-Pipeline konnte das Dokument nicht verarbeiten value: error: - Error extracting Document AI information schema: type: object additionalProperties: true '403': description: >- Zugriff verweigert. Wird zurückgegeben, wenn der Header `x-api-key` fehlt sowie wenn das Guthaben der aufrufenden Organisation den Aufruf nicht decken kann; ein falscher, widerrufener oder abgelaufener Schlüssel gibt `401` zurück. Ein fehlender Schlüssel gibt `403` mit `{"detail": ...}` zurück; ein falscher, widerrufener oder abgelaufener Schlüssel gibt `401` zurück. Unzureichende Credits – sowie Organisationen mit Vertragsabrechnung, deren Preisliste keinen Eintrag für die Document AI API enthält – geben `403` mit `{"error": ...}` zurück, bevor eine Dokumentenverarbeitung stattfindet. content: application/json: examples: Missing or invalid API key: summary: >- Kein `x-api-key`-Header, oder der Schlüssel ist ungültig/widerrufen value: detail: You do not have permission to perform this action. Not enough credits: summary: >- Das Guthaben der Organisation reicht für den Aufruf nicht aus value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me Contract rate missing: summary: >- Über Vertrag abgerechnete Organisation, deren Preisliste keinen Document AI API-Eintrag enthält value: error: >- Document AI API is not included in your contract rate card. Contact support@didit.me to enable it. schema: type: object properties: detail: type: string error: type: string '429': description: >- Rate-Limit überschritten. POST/PATCH/DELETE-Endpoints teilen sich ein Budget von 300 Schreibanfragen pro Minute pro API-Schlüssel (Transaktionserstellungen und Ereignis-Ingestion haben ein separates Budget von 600). Die Antwort enthält die Header `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` und `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Mehr als 300 Schreibanfragen in der aktuellen Minute value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '503': $ref: '#/components/responses/DocumentProcessingBusy' security: - ApiKeyAuth: [] x-codeSamples: - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.document_ai.analyze( document=open("document.pdf", "rb"), fields="[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]", ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.documentAi.analyze({ document: await fileFromPath("document.pdf"), fields: "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.DocumentAi.Analyze(ctx, didit.DocumentAiAnalyzeParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tFields: \"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import me.didit.Didit; import me.didit.types.DocumentAiAnalyzeParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.documentAi().analyze(DocumentAiAnalyzeParams.builder() .document(Path.of("document.pdf")) .fields("[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]") .build()); System.out.println(result); - lang: php label: PHP source: |- documentAi->analyze([ 'document' => File::fromPath('document.pdf'), 'fields' => '[{"key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false}, {"key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true}, {"key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false}, {"key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false}]', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.document_ai.analyze( document: Pathname("document.pdf"), fields: "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.DocumentAi.AnalyzeAsync(new DocumentAiAnalyzeParams { Document = FileUpload.FromPath("document.pdf"), Fields = "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: DocumentAIDetectedCode: type: object required: - type - page_number - position - x - 'y' - width - height - page_width - page_height - raw_payload - parsed_payload properties: type: type: string description: >- Erkannte Symbologie, zum Beispiel `QR_CODE`, `CODE_128`, `EAN_13`, `DATA_MATRIX` oder `PDF_417`. page_number: type: integer minimum: 1 description: 1-basierte Seitennummer. position: type: array nullable: true description: >- Erkanntes Polygon in Pixelkoordinaten der gerenderten Seite. `null`, wenn keine verlässliche Position verfügbar ist. items: type: array minItems: 2 maxItems: 2 items: type: integer x: type: integer nullable: true description: Linke Kante der Bounding-Box in Pixeln der gerenderten Seite. 'y': type: integer nullable: true description: Oberer Rand des Begrenzungsrahmens in Pixeln der gerenderten Seite. width: type: integer nullable: true description: Breite der Bounding-Box in Pixeln der gerenderten Seite. height: type: integer nullable: true description: Höhe der Bounding-Box in Pixeln der gerenderten Seite. page_width: type: integer description: Gerenderte Seitenbreite in Pixeln. page_height: type: integer description: Gerenderte Seitenhöhe in Pixeln. raw_payload: type: string description: >- Unverarbeitete Decoder-Payload als Base64-String, falls verfügbar; andernfalls ein leerer String. parsed_payload: nullable: true description: >- Dekodierte Zeichenkette oder strukturierter Wert. `null`, wenn der Code gefunden wurde, aber nicht dekodiert werden konnte. responses: DocumentProcessingBusy: description: >- Zurzeit werden zu viele Dokumente verarbeitet, daher wurde dieser Upload nicht verarbeitet: Es wurde nichts gespeichert und kein Versuch verbraucht. Senden Sie dieselbe Datei nach der in `Retry-After` angegebenen Anzahl an Sekunden erneut. Verzweigen Sie anhand von `code`, nicht anhand des Nachrichtentexts. headers: Retry-After: description: >- Sekunden, die gewartet werden müssen, bevor dieselbe Anfrage erneut gesendet wird. schema: type: integer example: 10 content: application/json: schema: type: object required: - detail - code properties: detail: type: string code: type: string enum: - document_processing_busy example: detail: We are busy processing documents. Please try again in a moment. code: document_processing_busy securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Der API-Schlüssel Ihrer Anwendung, aus Entwickler -> API-Schlüssel in der Business Console. Der Primärschlüssel hat Vollzugriff. Ein benannter Schlüssel kann im Geltungsbereich eingeschränkt werden: keine, Lese- oder Schreibberechtigung pro Ressource, beschränkt auf bestimmte Workflows oder genehmigte Sitzungen, auf eine Liste von IP-Adressen und auf ein Ablaufdatum. 401 bedeutet, dass der Schlüssel falsch, widerrufen oder abgelaufen ist; 403 bedeutet, dass kein Schlüssel gesendet wurde, der Schlüssel keinen Zugriff auf diese Ressource oder Aktion hat oder die Anfrage von einer Adresse außerhalb seiner IP-Liste stammte; 404 bei einer Sitzungsroute bedeutet, dass die Sitzung außerhalb der Workflows oder Status des Schlüssels liegt. Ein Schlüssel ohne Medienzugriff erhält Bild-, Video- und PDF-URLs als null, und ein Schlüssel ohne Schreibberechtigung für Sitzungen erhält Sitzungslinks und Token als null. Siehe https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.