> ## 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. # Proof of Address API: Adressnachweis-Verifizierung & OCR > POST /v3/poa/ prüft Stromrechnungen, Kontoauszüge und Mietverträge. Mit OCR-Adressextraktion, Echtheitsprüfung und Preisen pro Nutzung, ohne Vertrag. Didit. ## OpenAPI ````yaml de/openapi-25.json POST /v3/poa/ 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/poa/: post: tags: - Standalone APIs summary: Adressnachweis (Dokumenten-OCR + Adressprüfungen) description: >- Extrahieren und validieren Sie ein Adressnachweis-Dokument – Verbrauchsabrechnungen, Kontoauszüge und behördlich ausgestellte Dokumente – in einem einzigen Aufruf. Gibt den Aussteller, die Ausstellungs-/Ablaufdaten, den Namen des Inhabers, die Rohadresse und die analysierte/geokodierte Adresse, einen `status` von `Approved`/`Declined` sowie eine `warnings`-Liste zurück, die jedes gefundene Problem erläutert. **Latenz.** Die Extraktion basiert auf LLMs: 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 keinen Wiederholungsversuch durch, bevor der Aufruf abgeschlossen ist. **Funktionsweise.** Das Dokument (Bild oder PDF, bis zu 15 MB; verschlüsselte PDFs erfordern `document_password`) wird in einen Dokumenttyp und -subtyp klassifiziert (z. B. `UTILITY_BILL` / `WATER_BILL`), und Aussteller, Daten, Inhabername sowie Adresse werden per LLM-basierter Extraktion extrahiert. Die Adresse wird analysiert und in `poa_parsed_address` geokodiert. PDF-/EXIF-Forensik prüft auf Manipulationen – nachträgliche Änderungen nach digitaler Signatur, bekannte PDF-Editoren, Overlay-Text-Manipulationen, verdächtige Re-Exporte – und gibt `SUSPECTED_DOCUMENT_MANIPULATION` oder `DOCUMENT_METADATA_MISMATCH` aus. Ein Textfeld, das gelöscht und in einer anderen Schriftart neu eingegeben wurde, bei dem die Datei selbst keinen Beweis dafür enthält, ob sich der Inhalt geändert hat, führt zu `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`. Das Dokumentenalter wird anhand von `poa_document_age_months` validiert und die Sprache anhand von `poa_languages_allowed`. Wenn Sie `expected_address`, `expected_country` oder `expected_first_name`/`expected_last_name` übergeben, werden die extrahierten Werte abgeglichen und Abweichungen markiert. **Entscheidungslogik.** Der `status` ist `Approved`, sofern nicht mindestens eine Warnung zu einer Ablehnung führt. Harte Fehler führen immer zu einer Ablehnung: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE` sowie `UNABLE_TO_EXTRACT_ISSUE_DATE` und `POA_NAME_NOT_DETECTED` (auf diesem Endpoint nicht konfigurierbar). Fünf Risikogruppen sind pro Anfrage über die `poa_*_action`-Optionen konfigurierbar (`DECLINE` oder `NO_ACTION`, standardmäßig alle auf `DECLINE` gesetzt). `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` und `UNPARSABLE_OR_INVALID_ADDRESS` dienen auf diesem Endpoint nur als Information und führen nie zu einer Ablehnung. Ein Dokument, das überhaupt nicht verarbeitet werden kann, gibt `400` zurück; ein lesbares, aber problematisches Dokument gibt `200` mit `status: "Declined"` zurück – prüfen Sie daher stets `poa.status` und `poa.warnings`, nicht nur den HTTP-Code. **Abrechnung.** Jede `200`-Antwort verbraucht einen Adressnachweis-API-Credit (bezahlt über Ihr Tarif-Guthaben oder Aufladeguthaben). Wenn das Guthaben der Organisation den Aufruf nicht decken kann, gibt der Endpoint vor jeglicher Dokumentverarbeitung `403` mit dem Fehler für unzureichendes Guthaben zurück. **Sitzungspersistenz (`save_api_request`, Standard `true`).** Wenn `true`, wird der Aufruf als Sitzung vom Typ API beibehalten: Er erscheint in der Business Console, das hochgeladene Dokument wird gespeichert, die zurückgegebene `request_id` ist eine echte Sitzungs-ID, die Sie an `GET /v3/session/{sessionId}/decision/` übergeben können (die Entscheidung zeigt zusätzlich `document_file` und die Forensikdaten aus `document_metadata` an, die in dieser Antwort weggelassen werden), und ein `status.updated`-Webhook wird ausgelöst. Wenn `false`, wird nichts gespeichert und `request_id` ist eine einmalige Korrelations-UUID, die später nicht nachgeschlagen werden kann. **Sandbox.** Sandbox-API-Schlüssel überspringen die gesamte Verarbeitung und Abrechnung: Nach der Validierung der Anfrage (ungültige Eingaben geben weiterhin `400` zurück) gibt der Endpoint eine statische `Approved`-Mock-Payload zurück (eine fiktive Stromrechnung von „Sandbox Power Co.“), es wird keine Sitzung gespeichert und es werden keine Credits verbraucht. **Authentifizierung.** Senden Sie den API-Schlüssel Ihrer Anwendung im `x-api-key`-Header. Fehlende oder ungültige Anmeldedaten führen zu `403` (`{"detail": "You do not have permission to perform this action."}`) – diese API gibt niemals `401` zurück. **Rate-Limit.** Geteiltes Schreibkontingent von 300 Anfragen/Min. pro API-Schlüssel über alle POST-/PATCH-/DELETE-Endpoints; bei Überschreitung wird `429` zurückgegeben. Hinweis: `FUTURE_ISSUE_DATE` und `POOR_DOCUMENT_QUALITY` existieren in Workflow-Sitzungen, werden aber von diesem eigenständigen Endpoint niemals erzeugt – ein Dokument mit Ausstellungsdatum in der Zukunft wird hier nicht automatisch abgelehnt. operationId: post_v3poa parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - document properties: document: type: string format: binary description: >- Das Adressnachweis-Dokument. Zulässige Dateiendungen: `tiff`, `jpg`, `jpeg`, `png`, `pdf`, `webp`. Maximale Upload-Größe: **15 MB** (größere Dateien werden mit `400` abgelehnt). Mehrseitige PDFs werden unterstützt (erhöhte Latenz zu erwarten); verschlüsselte PDFs erfordern `document_password`. Bilder werden vor der Verarbeitung automatisch komprimiert. document_password: type: string description: >- Passwort zur Entschlüsselung von `document`, wenn es sich um eine verschlüsselte PDF-Datei handelt. Das Senden einer verschlüsselten PDF-Datei ohne (oder mit einem falschen) Passwort gibt `400` zurück. writeOnly: true expected_address: type: string description: >- Gegen das Dokument zu verifizierende Adresse. Sie wird geocodiert und mit der extrahierten Adresse verglichen; eine Nichtübereinstimmung (oder eine erwartete Adresse, die nicht geocodiert/verifiziert werden kann) fügt `ADDRESS_MISMATCH_WITH_PROVIDED` hinzu, geregelt durch `poa_address_mismatch_action`. Die geocodierte Form wird in `expected_details_formatted_address` / `expected_details_parsed_address` zurückgegeben. example: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: type: string description: >- Land, das mit dem Dokument abgeglichen werden soll (ISO 3166-1-Code, z. B. `ARG` oder `AR`). Eine Nichtübereinstimmung mit dem Land des Dokuments fügt `POA_COUNTRY_MISMATCH_WITH_PROVIDED` hinzu, gesteuert durch `poa_address_mismatch_action`. example: ARG expected_first_name: type: string description: >- Vorname, der mit `name_on_document` abgeglichen werden soll (Fuzzy-Match, transliterationssensitiv). Ein Wert unter dem Übereinstimmungsschwellenwert fügt `NAME_MISMATCH_WITH_PROVIDED` hinzu, gesteuert durch `poa_address_mismatch_action`. example: Sophia expected_last_name: type: string description: >- Mit `name_on_document` abzugleichender Nachname, der zusammen mit `expected_first_name` für den Übereinstimmungswert herangezogen wird. example: Martinez poa_languages_allowed: type: string description: >- Kommagetrennte Liste der akzeptierten Dokumentensprachen als ISO 639-1-Codes (z. B. `en,es,fr`). Wenn weggelassen oder leer, werden **alle 51 unterstützten Sprachen** akzeptiert. Ein Dokument in einer Sprache außerhalb der Liste fügt `UNSUPPORTED_DOCUMENT_LANGUAGE` hinzu (gesteuert durch `poa_unsupported_language_action`); ein unbekannter Code in der Liste gibt `400` mit dem vollständigen Satz unterstützter Codes zurück. example: en,es poa_document_age_months: type: string description: >- Kommagetrennte `key:value`-Paare, die das maximale Dokumentenalter in Monaten pro Dokumenttyp festlegen – Schlüssel: `utility_bill`, `bank_statement`, `government_issued_document`, `other_poa_document`; Werte: `1`–`120` oder `-1` für unbegrenzt (keine Altersprüfung). Standardwerte bei Auslassung: `utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12`. Ein Dokument, das älter als sein Grenzwert ist, wird mit `POA_DOCUMENT_EXPIRED` abgelehnt. **Achtung:** Wenn Sie dieses Feld angeben, listen Sie *jeden* Typ auf, den Sie akzeptieren – ausgelassene Typen werden als nicht akzeptiert behandelt (informatives `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`) und ihre Altersprüfung wird übersprungen. example: utility_bill:3,bank_statement:6 poa_name_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Akzeptiert, wird jedoch **derzeit nicht angewendet** – Warnungen wegen Namensabweichungen (`NAME_MISMATCH_WITH_PROVIDED`) folgen stattdessen `poa_address_mismatch_action`. Legen Sie `poa_address_mismatch_action` fest, um das Verhalten bei Namens- und Adressabweichungen zu steuern. poa_document_issues_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Was bei Problemen mit der Dateiintegrität zu tun ist — in der Praxis wird von diesem Endpoint nur `DOCUMENT_METADATA_MISMATCH` erzeugt. poa_document_authenticity_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Was zu tun ist, wenn eine Dokumentenmanipulation vermutet wird (`SUSPECTED_DOCUMENT_MANIPULATION`) — z. B. wurde das PDF nach der digitalen Signatur geändert, mit einem bekannten PDF-Editor bearbeitet, weist eine Overlay-Text-Manipulation auf oder hat inkonsistente EXIF-Daten. Regelt auch `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (ein neu eingegebenes Textfeld, bei dem die Datei weder eine Änderung noch den Originalzustand belegen kann): `DECLINE` lehnt dies ebenfalls ab, `NO_ACTION` behält es als Warnung bei. poa_unsupported_language_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Was zu tun ist, wenn die Dokumentsprache außerhalb von `poa_languages_allowed` liegt (`UNSUPPORTED_DOCUMENT_LANGUAGE`). poa_address_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Was zu tun ist, wenn die extrahierten Details nicht mit den `expected_*`-Feldern übereinstimmen: `ADDRESS_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_WITH_PROVIDED` und `POA_COUNTRY_MISMATCH_WITH_PROVIDED` folgen alle dieser Aktion. poa_issuer_not_identified_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Was zu tun ist, wenn kein ausstellendes Unternehmen bzw. keine ausstellende Organisation auf dem Dokument identifiziert werden kann (`ISSUER_NOT_IDENTIFIED`). 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`, angekündigt über einen `status.updated`-Webhook, wobei das hochgeladene Dokument gespeichert wird. Wenn `false`, wird nichts gespeichert und `request_id` ist eine flüchtige UUID, die nur der Antwortkorrelation dient. 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 example: document: (binary JPEG/PNG/PDF of the utility bill or bank statement) expected_address: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: ARG expected_first_name: Sophia expected_last_name: Martinez poa_languages_allowed: en,es save_api_request: true vendor_data: user-123 responses: '200': description: >- Dokument verarbeitet. `poa.status` ist `Approved` oder `Declined`; jedes erkannte Problem wird einzeln in `poa.warnings` aufgeführt. Ein abgelaufenes, nicht übereinstimmendes oder verdächtiges Dokument gibt dennoch `200` mit `status: "Declined"` 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: >- Versorgungsrechnung fehlerfrei ausgelesen, keine Prüfungen auf erwartete Details value: request_id: 4b523a8d-ed32-45e4-8aa8-a89eda459d88 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2026-04-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA detected_codes: - type: QR_CODE page_number: 1 position: - - 820 - 1120 - - 1002 - 1120 - - 1002 - 1302 - - 820 - 1302 x: 820 'y': 1120 width: 182 height: 182 page_width: 1190 page_height: 1684 raw_payload: >- aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ== parsed_payload: https://aguasdelnorte.com/factura/998811 - type: CODE_128 page_number: 1 position: - - 112 - 1480 - - 560 - 1480 - - 560 - 1540 - - 112 - 1540 x: 112 'y': 1480 width: 448 height: 60 page_width: 1190 page_height: 1684 raw_payload: MDA5OTg4MTEwMDA0Mg== parsed_payload: '0099881100042' status: Approved warnings: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T02:29:02.439655+00:00' Declined - document too old: summary: >- Ausstellungsdatum ist älter als der zulässige Wert für `poa_document_age_months` value: request_id: f61681b8-9422-4378-ac3e-04c6a247fb45 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: POA_DOCUMENT_EXPIRED feature: PROOF_OF_ADDRESS additional_data: expiration_reason: age_window max_age_months: 3 document_subtype: WATER_BILL document_type: UTILITY_BILL issue_date: '2021-02-10' log_type: error short_description: Document expired long_description: >- The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:23:02.165493+00:00' Declined - name mismatch: summary: >- `expected_first_name`/`expected_last_name` stimmen nicht mit `name_on_document` überein value: request_id: 0a7f2f9c-58f1-4b8e-b1e3-2f6f9d4f7a21 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: NAME_MISMATCH_WITH_PROVIDED feature: PROOF_OF_ADDRESS additional_data: null log_type: error short_description: Name mismatch with provided information long_description: >- The full name on the document does not match the name from the user's verified identity documents, or the full name sent by API. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:27:21.330172+00:00' 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. poa: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved`, wenn keine Warnung zu einer Ablehnung führt; andernfalls `Declined` — die Liste `warnings` erklärt warum. issuing_state: type: string nullable: true description: >- Land, in dem das Dokument ausgestellt wurde, wie aus dem Dokument extrahiert – üblicherweise ISO 3166-1 Alpha-3 (z. B. `ARG`). example: ARG document_type: type: string enum: - UTILITY_BILL - BANK_STATEMENT - GOVERNMENT_ISSUED_DOCUMENT - OTHER_POA_DOCUMENT - UNKNOWN description: >- Erkannte Dokumentenkategorie. `UNKNOWN` bedeutet, dass das Dokument nicht als zulässiger Adressnachweis klassifiziert werden konnte, und führt zur automatischen Ablehnung mit `INVALID_DOCUMENT_TYPE`. Niemals null — bei Klassifizierungsfehlern wird auf `UNKNOWN` zurückgegriffen. document_subtype: type: string description: >- Feinere Klassifizierung innerhalb von `document_type` – z. B. `ELECTRICITY_BILL`, `WATER_BILL`, `GAS_BILL`, `INTERNET_BILL`, `PHONE_BILL` (Verbrauchsabrechnungen); `ACCOUNT_STATEMENT`, `CREDIT_CARD_STATEMENT` (Kontoauszüge); `TAX_ASSESSMENT`, `RESIDENCY_CERTIFICATE` (behördliche Dokumente). `UNKNOWN`, wenn kein Subtyp bestimmt werden konnte. Niemals null – Klassifizierungsfehler fallen auf `UNKNOWN` zurück. example: WATER_BILL document_language: type: string nullable: true description: Erkannte Dokumentensprache (ISO 639-1). example: es issuer: type: string nullable: true description: >- Unternehmen oder Organisation, die das Dokument ausgestellt hat. `null` fügt `ISSUER_NOT_IDENTIFIED` hinzu. example: Aguas del Norte issue_date: type: string format: date nullable: true description: >- Dokumentenausstellungsdatum (`YYYY-MM-DD`). `null`, wenn es nicht extrahiert werden konnte – dies führt an diesem Endpoint zu einer Ablehnung mit `UNABLE_TO_EXTRACT_ISSUE_DATE`. example: '2021-02-10' expiration_date: type: string format: date nullable: true description: >- Explizites Ablauf-/Gültigkeitsdatum, das auf dem Dokument aufgedruckt ist, sofern vorhanden. Unabhängig von der Altersprüfung `poa_document_age_months`. poa_address: type: string nullable: true description: >- Adresse genau wie auf dem Dokument aufgedruckt. `null` führt zur automatischen Ablehnung mit `MISSING_ADDRESS_INFORMATION`. poa_formatted_address: type: string nullable: true description: Geocodierte, normalisierte Version von `poa_address`. example: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: type: object nullable: true description: >- Strukturierte, geocodierte Aufschlüsselung der Dokumentadresse. `null`, wenn die Adresse nicht analysiert werden konnte. properties: street_1: type: string nullable: true example: Avenida Monseñor Tavella 1291 street_2: type: string nullable: true city: type: string nullable: true example: Salta region: type: string nullable: true example: Salta country: type: string nullable: true description: ISO 3166-1 Alpha-2-Ländercode. example: AR postal_code: type: string nullable: true example: A4400 document_location: type: object nullable: true properties: latitude: type: number longitude: type: number description: Geocodierte Koordinaten der Dokumentadresse. expected_details_address: type: string nullable: true description: >- Rückgabe der von Ihnen gesendeten `expected_address` oder `null`. expected_details_formatted_address: type: string nullable: true description: >- Geocodierte, normalisierte Version von `expected_address`; `null`, wenn nicht angegeben oder nicht geocodierbar. expected_details_parsed_address: type: object nullable: true additionalProperties: true description: >- Vollständiges Geocoding-Ergebnis für `expected_address` (Straße/Stadt/Region/Land/Postleitzahl plus Rohdaten des Geocoders und ein `is_verified`-Flag). `null`, wenn `expected_address` nicht angegeben wurde. name_on_document: type: string nullable: true description: >- Aus dem Dokument extrahierter Name des primären Inhabers; wird mit `expected_first_name`/`expected_last_name` abgeglichen, sofern angegeben. Bei `null` wird an diesem Endpoint mit `POA_NAME_NOT_DETECTED` abgelehnt. example: OESTE EMBOTELLADORA S.A. extra_fields: type: object description: >- Dokumentspezifische Zusatzfelder. Bankfelder werden für Kontoauszüge ausgefüllt, wenn sie auf dem Dokument aufgedruckt sind; andernfalls `null`. properties: bank_account_number: type: string nullable: true bank_iban: type: string nullable: true bank_sort_code: type: string nullable: true bank_routing_number: type: string nullable: true bank_swift_bic: type: string nullable: true bank_branch_name: type: string nullable: true bank_branch_address: type: string nullable: true document_phone_number: type: string nullable: true description: >- Auf dem Dokument aufgedruckte Telefonnummer des Kontakts. additional_names: type: array items: type: string description: >- Andere auf dem Dokument gefundene Inhabernamen (z. B. Kontomitinhaber, frühere Kontonamen). 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`. items: type: object properties: risk: type: string description: >- Maschinenlesbarer Risiko-Code. Führt immer zur Ablehnung: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE` sowie `UNABLE_TO_EXTRACT_ISSUE_DATE` und `POA_NAME_NOT_DETECTED` (an diesem Endpoint fest auf Ablehnung eingestellt). Gesteuert über Anfrageoptionen: `NAME_MISMATCH_WITH_PROVIDED` / `ADDRESS_MISMATCH_WITH_PROVIDED` / `POA_COUNTRY_MISMATCH_WITH_PROVIDED` (`poa_address_mismatch_action`), `POOR_DOCUMENT_QUALITY` (wird an diesem Endpoint nie erzeugt) / `DOCUMENT_METADATA_MISMATCH` (`poa_document_issues_action`), `SUSPECTED_DOCUMENT_MANIPULATION` und `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (`poa_document_authenticity_action`), `UNSUPPORTED_DOCUMENT_LANGUAGE` (`poa_unsupported_language_action`), `ISSUER_NOT_IDENTIFIED` (`poa_issuer_not_identified_action`). An diesem Endpoint rein informativ: `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`, `UNPARSABLE_OR_INVALID_ADDRESS`. example: POA_DOCUMENT_EXPIRED feature: type: string enum: - PROOF_OF_ADDRESS description: >- Funktion, die die Warnung ausgelöst hat. An diesem Endpoint immer `PROOF_OF_ADDRESS`. additional_data: type: object nullable: true additionalProperties: true description: >- Zusätzlicher Kontext für einige Risiken — z. B. enthält `POA_DOCUMENT_EXPIRED` den `expiration_reason` (`printed_expiration` oder `age_window`), `document_type`, `document_subtype` und `issue_date` sowie `expiration_date` beim Pfad `printed_expiration` oder `max_age_months` beim Pfad `age_window`; `SUSPECTED_DOCUMENT_MANIPULATION` enthält `reason` und `detection_method`; `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` enthält `reason`, `detection_method` (`unproven_text_replacement`), `replaced_text`, `manipulated_regions` und `manipulated_blocks`. `null` für die meisten Risiken. log_type: type: string enum: - error - information description: >- Schweregrad. `error`-Warnungen setzen `status` auf `Declined`; `information`-Einträge sind hinweisend und führen für sich allein nie zu einer Ablehnung. (`warning` wird von diesem Endpoint nicht erzeugt — seine Optionen akzeptieren nur `DECLINE` oder `NO_ACTION`.) short_description: type: string description: >- Für Menschen lesbare einzeilige Zusammenfassung des Risikos. long_description: type: string description: Lesbare Erklärung des Risikos. detected_codes: type: array description: >- Auf jeder verarbeiteten Seite des Dokuments 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' 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: >- ISO 8601-Zeitstempel (UTC), wann die Antwort generiert wurde. '400': description: >- Validierungs- oder Verarbeitungsfehler. Probleme auf Feldebene geben das Standardantwortformat von DRF zurück (ein Array von Meldungen pro betroffenem Feld). Probleme mit verschlüsselten PDFs geben `{"detail": ...}` zurück. Ein Dokument, das die Extraktions-Pipeline nicht verarbeiten kann, gibt `{"error": ["Error extracting POA information"]}` zurück. content: application/json: examples: Missing document: summary: '`document` ist nicht in den Formulardaten enthalten' value: document: - No file was submitted. Unsupported file extension: summary: Dateiendung außerhalb von tiff/jpg/jpeg/png/pdf/webp value: document: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, pdf, webp. File too large: summary: Der Upload überschreitet das Limit von 15 MB value: document: - File size should not exceed 15 MB Encrypted PDF: summary: PDF ohne das erforderliche Passwort hochgeladen value: detail: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Wrong PDF password: summary: '`document_password` entschlüsselt die PDF nicht' value: detail: >- The PDF password is incorrect. Please provide the correct password. Invalid language code: summary: >- `poa_languages_allowed` enthält einen nicht unterstützten Code value: poa_languages_allowed: - >- Invalid language code: 'xx'. Must be one of the supported languages: ['ar', 'bn', 'hy', 'bg', 'bs', 'ca', 'cnr', 'sq', 'zh', 'hr', 'cs', 'da', 'nl', 'en', 'et', 'fi', 'fr', 'ka', 'kk', 'de', 'el', 'he', 'hi', 'hu', 'id', 'it', 'ja', 'ko', 'ky', 'lv', 'lt', 'mk', 'mn', 'ms', 'no', 'fa', 'pl', 'pt', 'ro', 'ru', 'sr', 'sk', 'sl', 'so', 'es', 'sv', 'th', 'tr', 'uk', 'uz', 'vi']. Invalid document age value: summary: '`poa_document_age_months`-Wert außerhalb von 1–120 / -1' value: poa_document_age_months: - >- Invalid integer value for 'utility_bill': '999'. Must be -1 (unlimited) or a positive integer between 1 and 120. Extraction failure: summary: >- Das Dokument konnte von der Extraktions-Pipeline nicht verarbeitet werden value: error: - Error extracting POA information '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 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 '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: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/poa/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'document=@./utility-bill.pdf' \ -F 'expected_address=Av. Monseñor Tavella 1291, Salta, Argentina' \ -F 'expected_country=ARG' \ -F 'expected_first_name=Sophia' \ -F 'expected_last_name=Martinez' \ -F 'poa_languages_allowed=en,es' \ -F 'vendor_data=user-123' \ --max-time 45 - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.proof_of_address.verify( document=open("document.pdf", "rb"), expected_address="Av. Monseñor Tavella 1291, Salta, Argentina", expected_country="ARG", expected_first_name="Sophia", expected_last_name="Martinez", poa_languages_allowed="en,es", save_api_request=True, vendor_data="user-123", ) 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.proofOfAddress.verify({ document: await fileFromPath("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tExpectedAddress: didit.String(\"Av. Monseñor Tavella 1291, Salta, Argentina\"),\n\tExpectedCountry: didit.String(\"ARG\"),\n\tExpectedFirstName: didit.String(\"Sophia\"),\n\tExpectedLastName: didit.String(\"Martinez\"),\n\tPOALanguagesAllowed: didit.String(\"en,es\"),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\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.ProofOfAddressVerifyParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.proofOfAddress().verify(ProofOfAddressVerifyParams.builder() .document(Path.of("document.pdf")) .expectedAddress("Av. Monseñor Tavella 1291, Salta, Argentina") .expectedCountry("ARG") .expectedFirstName("Sophia") .expectedLastName("Martinez") .poaLanguagesAllowed("en,es") .saveApiRequest(true) .vendorData("user-123") .build()); System.out.println(result); - lang: php label: PHP source: |- proofOfAddress->verify([ 'document' => File::fromPath('document.pdf'), 'expected_address' => 'Av. Monseñor Tavella 1291, Salta, Argentina', 'expected_country' => 'ARG', 'expected_first_name' => 'Sophia', 'expected_last_name' => 'Martinez', 'poa_languages_allowed' => 'en,es', 'save_api_request' => true, 'vendor_data' => 'user-123', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.proof_of_address.verify( document: Pathname("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123" ) 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.ProofOfAddress.VerifyAsync(new ProofOfAddressVerifyParams { Document = FileUpload.FromPath("document.pdf"), ExpectedAddress = "Av. Monseñor Tavella 1291, Salta, Argentina", ExpectedCountry = "ARG", ExpectedFirstName = "Sophia", ExpectedLastName = "Martinez", PoaLanguagesAllowed = "en,es", SaveApiRequest = true, VendorData = "user-123", }); 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.