> ## 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. # Sitzung erstellen API: KYC/KYB-Verifizierung starten > POST /v3/session/ startet eine Sitzung mit Didit. Einheitlicher KYC/KYB-Endpoint, Abrechnung pro Nutzung, unter 2 s, $10 Guthaben/Monat. Prompt zum Erstellen einer Sitzung Prompt in die Zwischenablage kopieren \

\`Create a verification session via Didit's REST API.

Endpoint:
POST https://verification.didit.me/v3/session/

Authentication:
Use the x-api-key header with your Didit API key. The workflow's type (KYC or KYB) determines which kind of session is created — there is no separate endpoint for KYB.

Request body:
\- workflow_id (string, UUID, required) — Stable workflow UUID from /v3/workflows/. KYC workflows create User Verification sessions; KYB workflows create Business Verification sessions.
\- vendor_data (string, optional) — Your stable identifier for the entity (user or business). Strongly recommended: it binds the session to a User or Business entity and is used for duplicate detection across sessions.
\- callback (string, URL, optional): Where the hosted flow redirects the user when finished. Didit appends ?verificationSessionId={session_id}&status={status}. Falls back to the workflow default. When the application has allowed domains (allowed_domains on PATCH /v3/webhook/), an http or https callback must be on one of those origins (same scheme, host and port), otherwise creation fails with 400 on callback: "callback must be on one of the application's allowed domains: https://app.example.com". Custom URL schemes (app deep links such as myapp://) are always accepted. A workflow-default callback outside the allowed domains is not used for the redirect.
\- callback_method (string, optional, default "initiator") — One of "initiator", "completer", "both". Use "both" if the callback sometimes fails to fire.
\- metadata (object, optional) — Arbitrary JSON echoed back in responses and webhooks. Not shown to the user.
\- tags (array of strings, optional): Tags added to the session when it is created, by name, for example ["VIP", "ONBOARDING Q4"]. Up to 10, each up to 50 characters. Names are case-insensitive and stored in upper case; a name that does not exist yet in the application is created as a new tag. The tags show on the session in the console, where you can filter by them, and come back in the create response.
\- language (string, optional) — ISO 639-1 code for the verification UI (en, es, fr, de, pt, etc.). Defaults to browser detection.
\- contact_details (object, optional) — { email, send_notification_emails, email_lang, phone }. Pre-fills phone/email steps and (optionally) sends notification emails.
\- expected_details (object, optional) — Expected first_name, last_name, date_of_birth, nationality (ISO-3), id_country (ISO-3), expected_document_types (e.g. ["P","ID","DL","RP","SSC"]). Mismatches surface as decision warnings. For Business Verification (KYB) workflows, pass the business fields instead — company_name, registry_country, registration_number — to pre-fill the company registry search; registry_country is ISO 3166-1 alpha-2 and can include the state for state-level registries (e.g. "US-CA"), same format as the KYB Registry Search country_code. Person-level fields are ignored on KYB sessions.
\- portrait_image (string, base64, conditional) — Reference face for Biometric Authentication workflows (and graph workflows where Face Match runs before ID Verification). Max 2MB; JPEG, PNG, WebP, or TIFF. Optional when the vendor_data user already has a stored face: Didit reuses it automatically (approved liveness face, then ePassport chip photo, then ID document portrait, then a manually enrolled profile face). If omitted and no stored face exists, creation fails with 400. Ignored for other workflow types.
\- multi_account_segment (string, optional, max 64 chars) — Duplicate-detection realm inside your own organization. Duplicate face checks only compare this session against other sessions carrying the same segment, so an organization that runs separate account bases (personal vs business, or one per sub-client) does not see a person who legitimately holds one account in each reported as a duplicate. Omit it to use the single default realm — which is what every session uses today, so existing integrations are unaffected. Blocklist and allowlist matching ignore this field: a blocklisted face stays blocklisted in every segment.
\- sandbox_scenario (string, optional, sandbox applications only): Scenario slug from the sandbox catalog (GET /v1/sandbox/scenarios/). Expands the scenario's bundled magic values onto contact_details/expected_details so the session reproduces that outcome. Rejected with 400 on live applications. You can also arm or re-arm a scenario after create, as long as the session is still Not Started, via POST /v3/session/{session_id}/sandbox/arm/. See /integration/sandbox-testing.
\- user_state (string, optional, max 16 chars): Where the person lives, when you know it: an ISO 3166-2 code (US-IL) or a US state code or name (IL, Illinois). In Auto consent mode, Illinois, Texas or Colorado makes the flow ask for explicit biometric consent before the first face capture. 400 on an unrecognized value.
\- biometric_consent (object, optional): Consent you already collected: { given_at (ISO 8601, not in the future), text_version (max 64 chars) }. The flow does not ask again; the decision records it as given with trigger customer_collected.
\- sign (object, optional): { documents: [ { title, file_name, content_base64, fields } ], field_values: { : value } }. documents is for a workflow whose E-signature step takes documents from the session (signature_documents_source "session" or "both"). file_name ends in .pdf or .docx; content_base64 is the file in base64. Up to 20 documents and 50 MB in total; a PDF up to 20 MB and 100 pages, without a password, scripts or attachments; a Word file (.docx) up to 20 MB, converted to PDF while the request runs, at most 5 per session. fields is optional (up to 200 per document): signature, initials, full_name, date_signed, text, checkbox, email or data fields, each with a key unique in its document (^[a-z][a-z0-9_]{0,63}$), placed by page, x, y, width and height, or by anchor text ({ text, occurrence, offset_x, offset_y, width, height }). role defaults to the step's signer. field_values fills the fields whose prefill is "api.", on workflow and session documents alike: strings of 1 to 500 characters, booleans for checkboxes. 400 when the workflow has no E-signature step, takes workflow documents only and you sent documents, or needs session documents you didn't send; field_anchor_not_found, field_value_unknown, field_value_missing or field_value_invalid for fields and values. See /core-technology/electronic-signature/overview.

Idempotency:
Within one application, only one non-finished session can exist per (workflow_id, vendor_data). Calling create again with the same pair returns the existing session (and updates its callback + metadata, and adds any tags you send) instead of creating a duplicate. If you send sign again, its documents, fields and field values must be identical (same order, titles, file names, content, fields and values), or the call returns 400 { "sign": "signature_document_changed" }.

curl example:
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "",
"vendor_data": "user-42",
"callback": "https://yourapp.com/callback",
"metadata": { "plan": "premium" }
}'

Response (201 Created) — keys you must handle:
\- session_id (UUID) — use this on every subsequent /v3/session/{session_id}/... call.
\- session_kind ("user" | "business") — discriminator, dispatch on this.
\- session_number (int) — human-friendly per-application sequence.
\- session_token (string) — short-lived, embedded in the hosted URL. Treat as secret.
\- url (string) — hosted verification URL. Redirect the end user here. (Field name is "url", NOT "verification_url".)
\- status (string) — newly created sessions return "Not Started".
\- workflow_id, workflow_version, vendor_data, metadata, callback — echoed back.

See /reference/data-models for the full schema.

Failure modes:
\- 400 — { "workflow_id": ["Invalid workflow_id."] } when the UUID is unknown.
\- 400 — { "vendor_data": ["This user or business has been blocked and cannot create new verification sessions."] } when blocklisted.
\- 400 — { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } when out of credits.
\- 400 — { "portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first." } on a Face Match workflow when portrait_image is omitted and the vendor_data user has no stored face.
\- 401 — invalid or missing API key.
\- 403 — { "detail": "You do not have permission to perform this action." } when the key lacks write:sessions.
\- 429 — rate limited (600 successful calls/minute per token/IP). Honour Retry-After.

Disclosure & consent:
This endpoint generates a URL — it does not record that you obtained user consent. Show your privacy notice and any biometric-specific consent in your own UX before redirecting to the hosted flow.
For people covered by Illinois, Texas or Colorado law, the hosted flow and native SDK 4.10.0 or later can ask for explicit biometric consent before the selfie; native SDKs below 4.10.0 cannot show that step. See /getting-started/biometric-consent.

Next step:
After the user finishes (status changes to Approved / Declined / In Review), call GET https://verification.didit.me/v3/session/{session_id}/decision/ for the full decision — see /sessions-api/retrieve-session.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\
Einfügen in ## Unterstützung für KYC und KYBEin einziger Endpoint erstellt sowohl Benutzerverifizierungs- als auch Unternehmensverifizierungs-Sitzungen. Der **Typ des Workflows** bestimmt, welche Art entsteht:- Übergeben Sie eine `workflow_id` eines **KYC-Workflows** → Es wird eine Benutzerverifizierungs-Sitzung (KYC) erstellt. Antwort `session_kind: "user"`. - Übergeben Sie eine `workflow_id` eines KYB-Workflows → Es wird eine Unternehmensverifizierungs-Sitzung (KYB) erstellt. Antwort `session_kind: "business"`.Konfigurieren Sie Workflows in der Console unter *Workflows → Create workflow*. Ein Workflow ist bei der Erstellung entweder KYC oder KYB; den Typ können Sie später nicht mehr ändern.## Beispiele> [tab] Benutzerverifizierung (KYC) > > ```bash theme={null} > curl -X POST https://verification.didit.me/v3/session/ \ > -H "x-api-key: YOUR_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ > "workflow_id": "YOUR_KYC_WORKFLOW_ID", > "vendor_data": "user-42", > "callback": "https://yourapp.com/callback" > }' > ``` > > **Antwort (201 Created):** > > ```json theme={null} > { > "session_id": "4c5c7f3a-1f82-4f3b-8d8e-1a8d2d2f9b7a", > "session_kind": "user", > "session_number": 1024, > "session_token": "...", > "url": "https://verify.didit.me/session/...", > "status": "Not Started", > "workflow_id": "YOUR_KYC_WORKFLOW_ID", > "vendor_data": "user-42" > } > ```> [tab] Unternehmensverifizierung (KYB) > > ```bash theme={null} > curl -X POST https://verification.didit.me/v3/session/ \ > -H "x-api-key: YOUR_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ > "workflow_id": "YOUR_KYB_WORKFLOW_ID", > "vendor_data": "biz-acme-001", > "callback": "https://yourapp.com/callback" > }' > ``` > > **Antwort (201 Created):** > > ```json theme={null} > { > "session_id": "bs-01HJX1...", > "session_kind": "business", > "session_number": 89, > "session_token": "...", > "url": "https://verify.didit.me/session/...", > "status": "Not Started", > "workflow_id": "YOUR_KYB_WORKFLOW_ID", > "vendor_data": "biz-acme-001" > } > ```## E-Signatur-DokumenteWenn der Workflow einen [E-Signatur](https://docs.didit.me/de/core-technology/electronic-signature/overview.md)-Schritt enthält, der Dokumente aus der Sitzung übernimmt (`signature_documents_source` auf `session` oder `both` gesetzt), senden Sie diese in `sign.documents`. Jedes Dokument ist die Datei in Base64, sodass Didit sie nie von einer URL abrufen muss.```json theme={null} { "workflow_id": "YOUR_WORKFLOW_ID", "vendor_data": "user-42", "sign": { "documents": [ { "title": "Loan agreement", "file_name": "loan-agreement.pdf", "content_base64": "JVBERi0xLjcKJc...", "fields": [ { "key": "borrower_signature", "type": "signature", "label": "Borrower signature", "page": 3, "x": 0.1, "y": 0.78, "width": 0.32, "height": 0.06 }, { "key": "date_signed", "type": "date_signed", "label": "Date", "page": 3, "x": 0.6, "y": 0.8, "width": 0.2, "height": 0.03, "date_format": "DD/MM/YYYY" }, { "key": "loan_amount", "type": "data", "label": "Loan amount", "page": 1, "x": 0.34, "y": 0.31, "width": 0.3, "height": 0.03, "prefill": "api.loan_amount" }, { "key": "initials", "type": "initials", "anchor": { "text": "[[initials]]", "occurrence": "all", "offset_x": 0, "offset_y": -0.005, "width": 0.12, "height": 0.04 } } ] } ], "field_values": { "loan_amount": "12,000 EUR" } } } ```| Feld | Regeln | | - | - | | `title` | Wird dem Unterzeichner angezeigt. 1 bis 255 Zeichen. Standardwert ist `file_name`. | | `file_name` | Pflichtfeld. Endet auf `.pdf` oder `.docx`. 1 bis 255 Zeichen. | | `content_base64` | Pflichtfeld. Ein PDF darf bis zu 20 MB groß sein und 100 Seiten haben, ohne Passwort, Skripte oder angehängte Dateien. Eine Word-Datei darf bis zu 20 MB groß sein und wird während der Anfrage in ein PDF umgewandelt, und zwar in höchstens 25 Sekunden; für das PDF gelten dann dieselben Grenzen. Bis zu 5 Word-Dateien pro Sitzung. | | `fields` | Optional. Bis zu 200 [Felder](https://docs.didit.me/de/core-technology/electronic-signature/overview.md#felder-auf-dem-dokument), die im Dokument platziert werden, in der Feldstruktur ohne `id`. Jedes Feld benötigt einen `key` und einen `type` sowie entweder eine Position (`page`, `x`, `y`, `width` und `height`) oder einen [`anchor`](#felder-über-ankertext-platzieren). `role` ist standardmäßig der Unterzeichner des Schritts, `required` und `label` ergeben sich standardmäßig aus dem Typ. Didit setzt `position` anhand der Stelle, an der das Feld steht. Seiten und Positionen beziehen sich auf das PDF bzw. bei einer Word-Datei auf das umgewandelte PDF. |Ohne `fields` liest der Unterzeichner das Dokument und stimmt ihm zu.### Felder über Ankertext platzierenAnstelle einer Position kann ein Feld einen `anchor` tragen: einen Textabschnitt im Dokument, der die Stelle markiert, an der das Feld platziert wird. Anker eignen sich für Dokumente, die Sie für jede Sitzung erzeugen, zum Beispiel aus einer Word-Vorlage. Platzieren Sie Felder für Workflow-Dokumente in der Console.| Eigenschaft von `anchor` | Regeln | | - | - | | `text` | 1 bis 64 Zeichen, gesucht im Text des Dokuments. Bei einer Word-Datei im umgewandelten PDF. | | `occurrence` | `first` (Standard) platziert ein Feld an der ersten Fundstelle. `all` platziert ein Feld pro Fundstelle; die Keys ab dem zweiten erhalten `_2`, `_3` usw. | | `offset_x`, `offset_y` | Anteile der Seite. Die linke obere Ecke des Feldes ist die linke obere Ecke des Ankertextes plus diese Versätze. | | `width`, `height` | Größe des Feldes als Anteile der Seite. |Wenn der Text nicht im Dokument vorhanden ist, gibt der Aufruf `400` mit `field_anchor_not_found` und dem Key des Feldes zurück. Didit entfernt den Ankertext nicht aus dem PDF. Schreiben Sie ihn deshalb in derselben Farbe wie der Seitenhintergrund.### Feldwerte`sign.field_values` setzt den Wert jedes Feldes, dessen `prefill` `api.` ist, sowohl bei Workflow-Dokumenten als auch bei Sitzungsdokumenten. Es ist ein Objekt, dessen Schlüssel die ``-Namen dieser Felder sind. Werte sind Zeichenketten mit 1 bis 500 Zeichen für `text`- und `data`-Felder und boolesche Werte für eine `checkbox`.```json theme={null} { "workflow_id": "YOUR_WORKFLOW_ID", "vendor_data": "user-42", "sign": { "field_values": { "credit_limit": "3,000 EUR", "monthly_fee": "4.90 EUR" } } } ```| Fehler (`400`) | Wann | | - | - | | `field_value_unknown` | Ein Key, den kein Feld verwendet. | | `field_value_missing` | Ein Pflichtfeld, dessen `api.` keinen Wert hat. | | `field_value_invalid` | Ein Wert, der die [Validierung](https://docs.didit.me/de/core-technology/electronic-signature/overview.md#validierung) seines Feldes nicht besteht. |### Fehler und wiederholte AufrufeEine Sitzung umfasst insgesamt bis zu 20 Dokumente und 50 MB. Der Aufruf gibt `400` mit einem `sign`-Fehler zurück, wenn:- Der Workflow keinen E-Signatur-Schritt enthält. - Sie `sign.documents` gesendet haben, der Schritt aber nur Workflow-Dokumente übernimmt. - Der Schritt nur Sitzungsdokumente übernimmt und Sie keine gesendet haben, oder er keine Workflow-Dokumente hat und Sie ebenfalls keine gesendet haben. - Ein Dokument zu groß ist, kein gültiges Base64 ist oder kein unterstütztes Dateiformat hat. - Eine Word-Datei mit `signature_document_not_supported` abgelehnt wird oder nicht umgewandelt werden kann und `signature_document_conversion_failed` zurückgibt, jeweils mit dem `reason` aus [Unterstützte Dateien](https://docs.didit.me/de/core-technology/electronic-signature/overview.md#unterstützte-dateien). - Ein Feld ungültig ist, sein Anker nicht gefunden wird (`field_anchor_not_found`) oder ein [Feldwert](#feldwerte) abgelehnt wird.Rufen Sie den Erstellungsendpunkt erneut mit derselben `workflow_id` und demselben `vendor_data` auf, wird die ausstehende Sitzung zurückgegeben. Sendet dieser Aufruf `sign`, müssen Dokumente, Felder und Feldwerte mit denen des ersten Aufrufs identisch sein (gleiche Reihenfolge, Titel, Dateinamen, Inhalte, Felder und Werte). Jede Abweichung gibt `400` mit `{"sign": "signature_document_changed"}` zurück. Verwenden Sie dann ein anderes `vendor_data` oder warten Sie, bis die ausstehende Sitzung abgeschlossen ist.## Tests mit Sandbox-SzenarienIn einer Anwendung im Sandbox-Modus übergeben Sie `sandbox_scenario`, um ein deterministisches Ergebnis vorab zu laden (Genehmigung, eine bestimmte Ablehnung oder ein Szenario „in Prüfung“), ohne echte Anbieter aufzurufen oder Ihr Guthaben zu belasten:```json theme={null} { "workflow_id": "YOUR_SANDBOX_WORKFLOW_ID", "sandbox_scenario": "decline_document_expired" } ````sandbox_scenario` wird in Anwendungen in der Produktionsumgebung mit `400` abgelehnt. Wenn Sie das Ergebnis zum Zeitpunkt der Erstellung noch nicht kennen, können Sie das Szenario später über `POST /v3/session/{session_id}/sandbox/arm/` setzen oder erneut setzen, solange die Sitzung noch `Not Started` ist. Die Szenarioauswahl vor dem Start des gehosteten Ablaufs nutzt denselben Endpoint. Den vollständigen Szenariokatalog, das Register der Magic Values sowie Anfrage- und Antwortformat des Arm-Endpoints finden Sie unter [Sandbox und Testdaten](https://docs.didit.me/de/integration/sandbox-testing.md).## `vendor_data` verknüpft die Sitzung mit einer Entität- Bei KYC-Workflows wird eine Verknüpfung mit einer [Benutzer-Entität](https://docs.didit.me/de/entities/users/overview.md) hergestellt. Existiert der Benutzer nicht, wird er automatisch angelegt. - Bei KYB-Workflows wird eine Verknüpfung mit einer [Unternehmens-Entität](https://docs.didit.me/de/entities/businesses/overview.md) hergestellt. Ist sie neu, wird sie automatisch angelegt.Mehr dazu unter [Verknüpfung von Vendor-Daten](https://docs.didit.me/de/entities/vendor-data-linking.md).## Biometrische Einwilligung in Illinois, Texas und ColoradoDie gehostete Verifizierungsseite und das native SDK ab Version 4.10.0 können je nach Einwilligungsmodus der Anwendung und dem Standort der Person einen ausdrücklichen Schritt zur biometrischen Einwilligung anzeigen, bevor die erste Gesichtsaufnahme erfolgt. Zwei optionale Felder fließen in diese Entscheidung ein:- `user_state`: Wohnort der Person, sofern Sie ihn kennen (`US-IL`, `IL` oder `Illinois`). Im Auto-Modus fragt der Ablauf nach, wenn ein betroffener Bundesstaat angegeben ist. - `biometric_consent`: ein Objekt mit `given_at` und `text_version` für eine Einwilligung, die Sie bereits eingeholt haben. Der Ablauf fragt dann nicht erneut nach.Native SDKs unterhalb von 4.10.0 können diesen Schritt nicht anzeigen. Ihre Sitzungen laufen wie bisher, und die Entscheidung meldet die Einwilligung als nicht eingeholt. Siehe [Biometrische Einwilligung](https://docs.didit.me/de/getting-started/biometric-consent.md).## Wichtig: Offenlegung und Einwilligung erfolgen weiterhin in Ihrem Produkt`Create Session` erzeugt eine Verifizierungs-URL und ein Sitzungs-Token. Allein damit wird **nicht** nachgewiesen, dass Sie dem Benutzer die erforderlichen Hinweise gezeigt oder die für Ihren konkreten Anwendungsfall nötige Einwilligung eingeholt haben.Wenn Sie eine Didit-Sitzung aus Ihrer eigenen Anwendung, Website, einem SDK-Wrapper oder einem White-Label-Ablauf starten, sollten Sie die rechtlichen Anforderungen in Ihrer eigenen Benutzeroberfläche umsetzen, bevor der Benutzer mit der Aufnahme beginnt.## Empfohlene Checkliste vor der Verifizierung1. Teilen Sie dem Benutzer mit, dass **Ihr Unternehmen** die Verifizierung anfordert und dass **Didit** als Verifizierungsdienstleister bzw. Auftragsverarbeiter den Ablauf bereitstellt. 2. Verlinken Sie auf **Ihre Datenschutzerklärung** und alle für den Ablauf geltenden rechtlichen Bedingungen des Verantwortlichen. 3. Verlinken Sie auf den [Datenschutzhinweis zur Verifizierung](https://didit.me/terms/verification-privacy-notice) und die [Nutzungsbedingungen für Endbenutzer zur Identitätsverifizierung](https://didit.me/terms/identity-verification) von Didit. 4. Wenn Ihr Workflow Dokumentenaufnahme, Selfie-Aufnahme, Liveness oder biometrische Verfahren umfasst, holen Sie **ausdrückliche, aktive Einwilligung** ein, wo das anwendbare Recht oder Ihre rechtliche Position dies verlangt. 5. Wenn Sie eine eigene Benutzeroberfläche, eine eigene Domain oder einen reinen API-Ablauf verwenden, zeigen Sie diese Hinweise in Ihrem eigenen Produkt an, bevor Sie den Benutzer in den Didit-Ablauf schicken. 6. Bewahren Sie Ihren eigenen Nachweis über Hinweis- und Einwilligungstext, Zeitstempel und zugehörige Metadaten auf, sofern Ihre Rechtsabteilung einen Prüfpfad verlangt.> [!WARNING] > > Rechtliche Anforderungen unterscheiden sich je nach Rechtsordnung. White-Label-Branding hebt die Rolle von Didit im Verifizierungsablauf nicht auf. Lassen Sie Ihre Implementierung vor dem Start von einem Rechtsbeistand prüfen, wenn Sie in Rechtsordnungen mit biometriespezifischen Vorschriften tätig sind. ## OpenAPI ````yaml de/openapi-25.json POST /v3/session/ 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/session/: post: tags: - Sessions summary: Erstellen Sie eine Verifizierungssitzung description: >- Erstellen Sie eine Sitzung zur Benutzerverifizierung (KYC) oder Unternehmensverifizierung (KYB) und erhalten Sie eine gehostete Verifizierungs-`url` sowie einen `session_token`, um Ihren Endbenutzer weiterzuleiten oder die Seite einzubinden. Die `workflow_id` bestimmt, welche Verifizierungsschritte ausgeführt werden und ob es sich um eine KYC- oder KYB-Sitzung handelt. Rufen Sie diesen Endpoint von Ihrem Backend aus auf (niemals über den Browser – der API-Schlüssel ist geheim), wann immer ein Benutzer oder ein Unternehmen verifiziert werden muss: bei der Registrierung, vor einer sensiblen Aktion oder wenn eine erneute Verifizierung erforderlich ist. Voraussetzungen: ein veröffentlichter Workflow (erstellt auf der Seite [Workflows](https://docs.didit.me/de/console/workflows) in der Konsole) und ein API-Schlüssel der Anwendung mit verfügbaren Credits. Sandbox-Anwendungen umgehen die Credit-Prüfung. **Idempotenz:** Wenn `vendor_data` angegeben ist und bereits eine unvollendete Sitzung (`Not Started`, `In Progress`, `Resubmitted` oder `Awaiting User`) mit denselben `vendor_data` in der **aktuellsten veröffentlichten Version** des Workflows existiert (und diese Sitzung bereits eine gehostete Verifizierungs-URL hat), wird die bestehende Sitzung zurückgegeben (weiterhin `201`), anstatt ein Duplikat zu erstellen – wobei deren `callback` und `metadata` auf die neu übergebenen Werte aktualisiert werden. Eine unvollendete Sitzung, die auf einer älteren Version des Workflows erstellt wurde (die seitdem erneut veröffentlicht wurde), wird **nicht** wiederverwendet; stattdessen wird eine neue Sitzung erstellt, die an die neueste veröffentlichte Version gebunden ist. Sitzungen mit dem Status `Approved`, `Declined`, `In Review`, `Expired`, `Abandoned` oder `Kyc Expired` werden niemals wiederverwendet. **Nebeneffekte:** Die gehostete Verifizierungs-URL wird generiert und gespeichert; wenn `contact_details.send_notification_emails` `true` ist und eine E-Mail-Adresse angegeben wird, wird eine Einladungs-E-Mail zur Verifizierung gesendet. Die Sitzung läuft nach der im Workflow konfigurierten Sitzungsablaufzeit ab. Bei KYB-Workflows werden `contact_details.phone` und `expected_details` ignoriert. operationId: post_v3_session_create requestBody: required: true content: application/json: schema: type: object required: - workflow_id properties: workflow_id: type: string format: uuid description: >- Stabiler Identifikator des Workflows, der definiert, welche Verifizierungsschritte die Sitzung ausführt. Workflows werden auf der Seite [Workflows](/de/console/workflows) der Console erstellt und verwaltet. Die `workflow_id` legt zudem implizit fest, ob es sich bei der Sitzung um KYC oder KYB handelt. example: 11111111-2222-3333-4444-555555555555 x-readme-id: '0.0' vendor_data: type: string description: >- Eine eindeutige Kennung für den zu verifizierenden Benutzer, wie z. B. eine UUID, E-Mail-Adresse oder interne Benutzer-ID. Dieses Feld wird verwendet für: (1) **Benutzergruppierung** – Sitzungen mit demselben vendor_data werden im Reiter „Benutzer“ mit demselben Benutzerprofil verknüpft. (2) **Sitzungsübergreifende Duplikaterkennung** – bei der Prüfung auf doppelte Gesichter, Dokumente, Telefonnummern, E-Mails, IP-Adressen oder Geräte-Fingerprints werden Sitzungen mit demselben vendor_data als derselbe Benutzer behandelt und von den Treffern ausgeschlossen. Ohne vendor_data wird jede Sitzung als eindeutiger Benutzer behandelt und alle potenziellen Duplikate werden angezeigt. Wir empfehlen dringend, stets einen vendor_data-Wert anzugeben, um Fehlalarme bei der Duplikaterkennung zu reduzieren. example: user-123 x-readme-id: '0.1' multi_account_segment: type: string maxLength: 64 description: >- Optionaler Bereich zur Duplikaterkennung innerhalb Ihrer Organisation. Prüfungen auf doppelte Gesichter vergleichen diese Sitzung nur mit anderen Sitzungen, die dasselbe Segment aufweisen, sodass getrennte Kontobasen (Privat- und Geschäftskonten oder eines pro B2B-Sub-Client) eine Person nicht markieren, die berechtigterweise jeweils ein Konto führt. Weglassen, um den einzelnen Standardbereich zu nutzen, den derzeit jede Sitzung verwendet. Der Abgleich mit Sperrlisten und Positivlisten ignoriert dieses Feld. example: business-accounts callback: type: string description: >- URL, zu der der Benutzer nach Abschluss der Verifizierung weitergeleitet wird. Didit hängt `verificationSessionId` und `status` (Approved, Declined, In Review) automatisch als Query-Parameter an. Benutzerdefinierte URL-Schemata (z. B. `myapp://`) werden für mobile Callbacks unterstützt. Wenn weggelassen, wird die Standard-`callback_url` des Workflows verwendet. Wenn für die Anwendung erlaubte Domains konfiguriert sind (`allowed_domains` bei `PATCH /v3/webhook/`), muss ein `http`- oder `https`-Callback auf einer dieser Ursprungsdomains liegen (gleiches Schema, gleicher Host und Port), andernfalls schlägt die Anfrage mit 400 für `callback` fehl: `callback must be on one of the application's allowed domains: https://app.example.com`. Benutzerdefinierte URL-Schemata werden immer akzeptiert. example: https://example.com/verification/callback x-readme-id: '0.2' callback_method: type: string description: >- Bestimmt, welches Gerät die Weiterleitung zur angegebenen Callback-URL durchführen soll. Verwenden Sie `initiator`, um nur das Gerät weiterzuleiten, das den Ablauf gestartet hat, `completer` für das Gerät, das ihn beendet, oder `both`, damit jedes Gerät den Callback auslösen kann. Falls Sie feststellen, dass der Callback nicht zuverlässig ausgelöst wird, empfehlen wir, diesen Wert auf `both` zu setzen. enum: - initiator - completer - both default: initiator example: both x-readme-id: '0.3' metadata: description: >- Beliebiges JSON, das mit der Sitzung gespeichert und in der Antwort sowie in Webhooks unverändert zurückgegeben wird. Jeder JSON-Wert wird akzeptiert (Objekt, String, Zahl, Array), empfohlen wird jedoch ein JSON-Objekt aus Schlüssel-Wert-Paaren. Für den Endbenutzer nicht sichtbar. Nutzen Sie es, um eigene Korrelations-IDs, A/B-Varianten oder geschäftlichen Kontext zu übergeben. example: user_type: premium account_id: ABC123 x-readme-id: '0.4' tags: type: array items: type: string maxLength: 50 maxItems: 10 description: >- Tags, die der Sitzung bei ihrer Erstellung nach Namen hinzugefügt werden. Bis zu 10, jeweils bis zu 50 Zeichen. Bei Namen wird die Groß-/Kleinschreibung nicht beachtet; sie werden in Großbuchstaben gespeichert. Ein Name, der in der Anwendung noch nicht existiert, wird als neues Tag erstellt. Die Tags werden bei der Sitzung in der Console angezeigt, wo Sie nach ihnen filtern können. example: - VIP - ONBOARDING Q4 language: type: string description: >- Sprachcode (ISO 639-1) für die Oberfläche des Verifizierungsprozesses. Steuert die dem Endbenutzer während der Verifizierung angezeigte Sprache. Falls nicht angegeben, wird die Sprache des Browsers automatisch erkannt und verwendet. Eine Übersicht aller unterstützten Sprachen finden Sie [hier](/de/integration/supported-languages). enum: - en - ar - bg - bn - bs - ca - cnr - cs - da - de - el - es - et - fa - fi - fr - he - hi - hr - hu - hy - id - it - ja - ka - kk - ko - ky - lt - lv - mk - mn - ms - nl - 'no' - pl - pt-BR - pt - ro - ru - sk - sl - so - sq - sr - sv - th - tr - uk - uz - vi - zh-CN - zh-TW - zh example: en x-readme-id: '0.5' contact_details: type: object description: >- Kontaktinformationen des Benutzers, die für Benachrichtigungen, das Vorausfüllen von Verifizierungsformularen und die Telefonverifizierung verwendet werden können. Dazu gehören die E-Mail-Adresse, die bevorzugte Sprache für Mitteilungen und die Telefonnummer. example: email: john.doe@example.com send_notification_emails: true email_lang: en phone: '+14155552671' properties: email: type: string format: email description: >- E-Mail-Adresse des Benutzers (z. B. "john.doe@example.com"), die während des Schritts der [E-Mail-Verifizierung](/de/core-technology/email-verification/overview) verwendet wird. Falls nicht angegeben, muss der Benutzer sie während des Verifizierungsablaufs angeben. example: john.doe@example.com x-readme-id: '1.0' send_notification_emails: type: boolean default: false description: >- Wenn true und eine E-Mail-Adresse angegeben ist, sendet Didit die anfängliche E-Mail „Verifizieren Sie Ihre Identität“ asynchron, sobald die Sitzung zur Benutzerverifizierung (KYC) oder Unternehmensverifizierung (KYB) erstellt wird. Didit sendet außerdem Benachrichtigungen zum Verifizierungsstatus für Sitzungen, die eine manuelle Prüfung erfordern, an die angegebene E-Mail-Adresse (z. B. von „In Review“ zu „Approved“ oder „Declined“). Dies hilft Benutzern, zu Ihrer Anwendung zurückzukehren, sobald ihre Verifizierung abgeschlossen ist. Wenn Sie White-Label für die Sitzung aktiviert haben, wird die versendete E-Mail als White-Label versendet. example: true x-readme-id: '1.1' email_lang: type: string description: >- Sprachcode (ISO 639-1) für E-Mail-Benachrichtigungen. Steuert die Sprache aller E-Mail-Mitteilungen (z. B. „en“, „es“, „fr“). Es ist kein Standardwert hinterlegt — wird der Parameter weggelassen, fällt die Verifizierungseinladungs-E-Mail beim Versand einfach auf Englisch (`en`) zurück. Das nachfolgende Enum ist eine Momentaufnahme; die maßgebliche Quelle für akzeptierte Werte ist die Dokumentation zu den [unterstützten Sprachen](/de/integration/supported-languages) — ziehen Sie diese stets zu Rate, bevor Sie sich auf einen bestimmten Code verlassen. enum: - en - ar - bg - bn - bs - ca - cnr - cs - da - de - el - es - et - fa - fi - fr - he - hi - hr - hu - hy - id - it - ja - ka - kk - ko - ky - lt - lv - mk - mn - ms - nl - 'no' - pl - pt-BR - pt - ro - ru - sk - sl - so - sq - sr - sv - th - tr - uk - uz - vi - zh-CN - zh-TW - zh example: en x-readme-id: '1.2' phone: type: string description: >- Telefonnummer im E.164-Format (z. B. „+14155552671“), die während des Schritts [Telefonverifizierung](/de/core-technology/phone-verification/overview) verwendet wird. Falls nicht angegeben, muss der Benutzer sie während des Verifizierungs-Flows eingeben. Wird bei Workflows der Unternehmensverifizierung (KYB) ignoriert. **Wichtig:** Diese Telefonnummer wird nur durchgesetzt, wenn es sich um eine gültige E.164-Telefonnummer handelt. Wenn die angegebene Nummer ungültig ist oder nicht geparst werden kann, wird sie ignoriert und der Benutzer kann während des Telefonverifizierungsschritts eine beliebige gültige Telefonnummer eingeben. example: '+14155552671' x-readme-id: '1.3' x-readme-id: '0.4' expected_details: type: object description: >- Erwartete Benutzerdaten, die für die Kreuzvalidierung mit den aus dem Ausweisdokument des Benutzers, dem Adressnachweis und anderen Verifizierungsschritten extrahierten Daten verwendet werden. Abweichungen werden als Warnungen in der Entscheidung angezeigt; einige Felder (z. B. `id_country`, `expected_document_types`) verändern auch den für den Benutzer sichtbaren Ablauf. Bei Workflows zur Unternehmensverifizierung (KYB) werden nur die Unternehmensfelder (`company_name`, `registry_country`, `registration_number`) verwendet — sie füllen die Suche im Unternehmensregister für den Benutzer voraus — und alle Felder auf Personenebene werden ignoriert. example: first_name: John last_name: Doe date_of_birth: '1990-05-15' nationality: USA id_country: USA expected_document_types: - P - ID properties: first_name: type: string description: >- Vorname des Benutzers. Zum Beispiel `John`. Der Abgleich verwendet einen unscharfen Vergleich, und Sie können die Genauigkeit anpassen, indem Sie den Schwellenwert für den Namensübereinstimmungswert in der Konsole sowohl für Ausweisdokument- als auch für Adressnachweis-Workflows konfigurieren. example: John x-readme-id: '1.0' last_name: type: string description: >- Nachname des Benutzers. Zum Beispiel `Doe`. Der Abgleich verwendet einen unscharfen Vergleich, und Sie können die Genauigkeit anpassen, indem Sie den Schwellenwert für den Namensübereinstimmungswert in der Konsole sowohl für Ausweisdokument- als auch für Adressnachweis-Workflows konfigurieren. example: Doe x-readme-id: '1.1' date_of_birth: type: string format: date description: >- Geburtsdatum des Benutzers im Format: YYYY-MM-DD. Zum Beispiel `1990-05-15`. example: '1990-05-15' x-readme-id: '1.2' gender: type: string nullable: true enum: - M - F default: null description: >- Geschlecht des Benutzers. Muss entweder 'M', 'F' oder null sein. example: M x-readme-id: '1.3' nationality: type: string description: >- ISO 3166-1-Alpha-3-Ländercode, der das Herkunftsland des Antragstellers darstellt. Zum Beispiel `USA`. Siehe die [vollständige Liste der unterstützten Ländercodes](https://docs.didit.me/de/core-technology/id-verification/supported-documents-id-verification#unterstützte-dokumente-nach-land). example: USA x-readme-id: '1.4' country: type: string description: >- ISO 3166-1-Alpha-3-Ländercode, der als Fallback sowohl für Länderabgleichprüfungen der Ausweisverifizierung als auch des Adressnachweises dient. Erforderlich, wenn `address` angegeben ist und weder `id_country` noch `poa_country` festgelegt wurde. example: USA x-readme-id: 1.4.1 id_country: type: string description: >- ISO 3166-1-Alpha-3-Ländercode, der das erwartete Land des Ausweisdokuments des Antragstellers darstellt, welches von der Staatsangehörigkeit abweichen kann. Zum Beispiel `GBR`. Hat bei Länderabgleichprüfungen der Ausweisverifizierung Vorrang vor `country`. Siehe die [vollständige Liste der unterstützten Ländercodes](https://docs.didit.me/de/core-technology/id-verification/supported-documents-id-verification#unterstützte-dokumente-nach-land). example: GBR x-readme-id: '1.5' poa_country: type: string description: >- ISO 3166-1-Alpha-3-Ländercode, der das erwartete Land des Adressnachweis-Dokuments darstellt. Zum Beispiel `USA`. Hat bei Länderabgleichprüfungen des Adressnachweises (POA) Vorrang vor `country`. Siehe die [vollständige Liste der unterstützten Ländercodes](https://docs.didit.me/de/core-technology/id-verification/supported-documents-id-verification#unterstützte-dokumente-nach-land). example: USA x-readme-id: 1.5.1 address: type: string description: >- Die Adresse in einem menschenlesbaren Format, einschließlich so vieler Informationen wie möglich. Zum Beispiel `123 Main St, San Francisco, CA 94105, USA`. Wenn angegeben, müssen Sie auch `country` oder `poa_country` übergeben, andernfalls schlägt die Anfrage mit `400` fehl. example: 123 Main St, San Francisco, CA 94105, USA x-readme-id: '1.6' identification_number: type: string description: >- Die Dokumentennummer, persönliche Identifikationsnummer oder Steuernummer des Benutzers. Zum Beispiel `123456789`. example: '123456789' x-readme-id: '1.7' ip_address: type: string description: >- Erwartete IP-Adresse für die Sitzung im IPv4- oder IPv6-Format. Wenn die tatsächliche IP-Adresse von diesem Wert abweicht, wird eine Warnung protokolliert. Zum Beispiel `192.168.1.100` oder `2001:db8::1`. example: 192.168.1.100 x-readme-id: '1.8' expected_document_types: type: array description: >- Schränkt die Dokumenttypen ein, die der Benutzer während des Schritts zur Ausweisverifizierung (OCR) vorlegen kann. Wenn festgelegt, zeigt der Dokumentauswahlbildschirm nur die angeforderten Typen an und das zurückgegebene `documents_allowed` wird entsprechend gefiltert. Werte unterscheiden nicht zwischen Groß- und Kleinschreibung und werden dedupliziert; unbekannte Werte werden mit `400` abgewiesen. Zulässige Codes: `P` (Reisepass), `ID` (Personalausweis), `DL` (Führerschein), `RP` (Aufenthaltstitel), `HIC` (Krankenversicherungskarte), `TC` (Steuerkarte), `SSC` (Sozialversicherungsausweis). items: type: string enum: - P - ID - DL - RP - HIC - TC - SSC example: - P - ID x-readme-id: '1.9' company_name: type: string maxLength: 255 description: >- Erwarteter rechtlicher Name des zu verifizierenden Unternehmens. Zum Beispiel `Tesco PLC`. Füllt das Feld für den Unternehmensnamen bei der Suche im Unternehmensregister in Workflows zur Unternehmensverifizierung (KYB) voraus; wenn auch `registration_number` angegeben ist, kombiniert die Registerabfrage beide Identifikatoren. Wird bei KYC-Workflows ignoriert. example: Tesco PLC x-readme-id: '1.10' registry_country: type: string maxLength: 10 description: >- ISO 3166-1 Alpha-2-Code des Landes, in dessen Unternehmensregister das Unternehmen eingetragen ist. Zum Beispiel `GB`. Wenn Unternehmensregister auf Bundesstaat- oder Provinzebene geführt werden, hängen Sie den ISO 3166-2-Unterteilungscode als `XX-YY` an: `US-CA` zielt auf das kalifornische Register ab. Dasselbe Format wie `country_code` in der [KYB Registry Search API](https://docs.didit.me/de/standalone-apis/kyb-registry-search). Wählt das Registerland in Workflows der Unternehmensverifizierung (KYB) vor; wird bei KYC-Workflows ignoriert. example: US-CA x-readme-id: '1.11' registration_number: type: string maxLength: 100 description: >- Erwartete Registernummer des Unternehmens im Unternehmensregister. Zum Beispiel `00445790`. Füllt das Feld für die Registernummer bei der Suche im Unternehmensregister in Workflows zur Unternehmensverifizierung (KYB) voraus; wenn auch `company_name` angegeben ist, kombiniert die Registerabfrage beide Identifikatoren. Wird bei KYC-Workflows ignoriert. example: '00445790' x-readme-id: '1.12' x-readme-id: '0.5' portrait_image: type: string format: byte description: >- Base64-kodiertes Porträtbild des Gesichts des Endbenutzers (max. 2 MB; JPEG, PNG, WebP oder TIFF). Wird als Referenzbild für den Abgleich mit der Liveness-Aufnahme verwendet, wenn der Workflow ein `Biometric Authentication`-Workflow mit aktiviertem Gesichtsabgleich ist, oder bei jedem Graph-Workflow, bei dem der Gesichtsabgleich vor der Ausweisverifizierung (OCR) ausgeführt wird. Optional, wenn der `vendor_data`-Benutzer bereits ein gespeichertes Gesichtsbild hat: Didit verwendet dieses automatisch wieder, aufgelöst in dieser Prioritätsreihenfolge: genehmigtes Liveness-Gesicht, Foto vom ePass-Chip, Porträt aus dem Ausweisdokument, manuell registriertes Profilgesicht (nur Gesichter aus genehmigten Sitzungen oder Gesichter, die Sie selbst registriert haben, werden wiederverwendet). Falls angegeben, hat `portrait_image` immer Vorrang vor dem gespeicherten Gesicht. Wenn es weggelassen wird und kein gespeichertes Gesicht vorhanden ist (oder `vendor_data` nicht gesendet wird), schlägt die Sitzungserstellung mit `400` fehl. Wird bei anderen Workflow-Typen ignoriert. example: >- iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII= x-readme-id: '0.6' sandbox_scenario: type: string description: >- Szenario-Slug nur für die Sandbox. Wird nur akzeptiert, wenn der API-Schlüssel zu einer Anwendung im Sandbox-Modus gehört; bei Produktionsanwendungen abgelehnt. Wenn dieser Parameter festgelegt ist, überträgt der Erstellungsablauf die gebündelten Magic Values des Szenarios auf die Eingabefelder der Sitzung (contact_details, expected_details), sodass die gemockten Provider das Ergebnis des Szenarios über die reale Workflow-Pipeline reproduzieren. Siehe den Szenarienkatalog unter GET /v1/sandbox/scenarios/ oder [Sandbox & Test Data](/de/integration/sandbox-testing). Sie können ein Szenario nach der Erstellung auch über POST /v3/session/{sessionId}/sandbox/arm/ aktivieren (oder erneut aktivieren), solange sich die Sitzung noch im Status `Not Started` befindet. Verwenden Sie für Lookups ohne Dokument `lookup_partial_match`, `lookup_no_match` oder `lookup_provider_error`, um das konfigurierte Versuchsbudget und den Fallback zu testen. Verwenden Sie für Identitäts-Wallets `wallet_cancelled`, `wallet_timeout` oder `wallet_provider_error`; `approve` simuliert eine verifizierte Wallet. Alle Katalog-Wallets können in der Sandbox getestet werden, einschließlich Schemas, die in Produktionsanwendungen nicht verfügbar sind. Simulierte Versuche werden nicht abgerechnet. example: decline_document_expired sign: type: object description: >- E-Signatur-Eingabe für diese Sitzung. `documents` sind die zu unterzeichnenden Dokumente für einen Workflow, dessen E-Signatur-Schritt Dokumente aus der Sitzung übernimmt (`signature_documents_source` `session` oder `both`): bis zu 20 Dokumente und insgesamt 50 MB. `field_values` füllt die Felder aus, deren `prefill` `api.` ist, sowohl auf Workflow- als auch auf Sitzungsdokumenten. Ein erneutes Erstellen einer Sitzung für dieselbe `workflow_id` und `vendor_data` gibt die ausstehende Sitzung zurück; wenn dieser Aufruf `sign` sendet, müssen die Dokumente, Felder und Werte mit den ersten identisch sein, andernfalls wird `400` mit `{"sign": "signature_document_changed"}` zurückgegeben. Siehe [E-Signatur-Dokumente](/de/sessions-api/create-session#e-signatur-dokumente). properties: documents: type: array minItems: 1 maxItems: 20 items: $ref: '#/components/schemas/SessionSignDocument' field_values: type: object description: >- Werte, aufgeschlüsselt nach dem `` jeder `api.`-Vorausfüllquelle: Strings von 1 bis 500 Zeichen für `text`- und `data`-Felder, boolesche Werte für eine `checkbox`. `400` mit `field_value_unknown` für einen Schlüssel, den kein Feld verwendet, `field_value_missing` für ein Pflichtfeld ohne Wert und `field_value_invalid` für einen Wert, der die Validierung seines Felds nicht besteht. additionalProperties: oneOf: - type: string minLength: 1 maxLength: 500 - type: boolean example: credit_limit: 3,000 EUR user_state: type: string maxLength: 16 description: >- Wohnort der Person, falls bekannt: ein Code für eine ISO-3166-2-Unterteilung (`US-IL`, `ES-M`) oder ein US-Bundesstaatscode oder -name (`IL`, `Illinois`). Bei einem Bundesstaat, dessen Recht eine ausdrückliche biometrische Einwilligung vorschreibt (Illinois, Texas, Colorado), fordert der Verifizierungs-Workflow diese vor der Erfassung eines Gesichts mit dem Auslöser `declared_state` an. Ein nicht erkannter Wert gibt `400` zurück. Siehe [Biometrische Einwilligung](/de/getting-started/biometric-consent). example: US-IL biometric_consent: type: object description: >- Explizite biometrische Einwilligung, die Sie bereits von der Person eingeholt haben. Sie erfüllt die Anforderung, sodass im Verifizierungsablauf nicht erneut gefragt wird und die Entscheidung dies als `status: "given"` mit dem Auslöser `customer_collected` erfasst. Eine Antwort, die die Person bereits im Ablauf gegeben hat, wird niemals ersetzt. Siehe [Biometrische Einwilligung](/de/getting-started/biometric-consent). required: - given_at - text_version properties: given_at: type: string format: date-time description: >- Wann die Person die ausdrückliche biometrische Einwilligung erteilt hat (ISO 8601). Darf nicht in der Zukunft liegen. text_version: type: string maxLength: 64 description: >- Versions-ID des Einwilligungstextes, den die Person akzeptiert hat, in Ihren eigenen Datensätzen. example: workflow_id: 11111111-2222-3333-4444-555555555555 vendor_data: user-123 callback: https://example.com/verification/callback callback_method: both metadata: user_type: premium account_id: ABC123 language: en contact_details: email: john.doe@example.com send_notification_emails: true email_lang: en phone: '+14155552671' expected_details: first_name: John last_name: Doe date_of_birth: '1990-05-15' id_country: USA expected_document_types: - P - ID examples: Create KYC session: summary: >- Vollständige Happy-Path-Payload für eine Benutzerverifizierungs-Sitzung (KYC) description: >- Realistischer Erstellungsaufruf, der alle gängigen Felder verwendet: Workflow-Auswahl, Anbieter-Verknüpfung, Callback-Routing, Metadaten, Spracheinstellung, Vorbefüllung von Kontaktdaten und erwartete Benutzerdetails. Kopieren Sie dies direkt in das obige cURL-Beispiel. value: workflow_id: 11111111-2222-3333-4444-555555555555 vendor_data: user-123 callback: https://example.com/verification/callback callback_method: both metadata: user_type: premium account_id: ABC123 language: en contact_details: email: john.doe@example.com send_notification_emails: true email_lang: en phone: '+14155552671' expected_details: first_name: John last_name: Doe date_of_birth: '1990-05-15' nationality: USA id_country: USA expected_document_types: - P - ID Create KYB session: summary: >- Payload für den Erfolgsfall einer Sitzung der Unternehmensverifizierung (KYB) description: >- Gleiche Struktur wie der KYC-Aufruf — die `workflow_id` bestimmt, dass es sich bei der Sitzung um KYB handelt. `vendor_data` verweist typischerweise auf das Unternehmen in Ihrem System und `contact_details.email` richtet sich an den gesetzlichen Vertreter, der den Ablauf abschließt. `expected_details` akzeptiert die Unternehmensfelder (`company_name`, `registry_country`, `registration_number`), die die Unternehmensregistersuche vorausfüllen; personenbezogene Felder und `contact_details.phone` werden bei KYB-Workflows ignoriert. value: workflow_id: 33333333-4444-5555-6666-777777777777 vendor_data: company-acme-001 callback: https://example.com/kyb/callback callback_method: both metadata: tier: enterprise company_id: ACME-001 expected_details: company_name: Tesco PLC registry_country: GB registration_number: '00445790' language: en contact_details: email: legal-rep@acme.example.com send_notification_emails: true email_lang: en responses: '201': description: >- Sitzung erstellt (oder zurückgegeben, wenn eine nicht abgeschlossene Sitzung mit denselben `vendor_data` bereits in der neuesten veröffentlichten Version des Workflows existiert). Die Antwort ist die serialisierte Sitzung, einschließlich der gehosteten Verifizierungs-`url`, zu der der Benutzer weitergeleitet werden soll. content: application/json: schema: type: object required: - session_id - session_number - session_token - url - vendor_data - metadata - status - workflow_id - workflow_version - callback properties: session_id: type: string format: uuid description: >- Eindeutige Kennung der Verifizierungssitzung. Verwenden Sie diese ID beim Aufruf von `GET /v3/session/{sessionId}/decision/`. example: 11111111-2222-3333-4444-555555555555 session_number: type: integer description: >- Fortlaufende, lesbare Nummer, die der Sitzung innerhalb Ihrer Anwendung zugewiesen wurde. Nützlich für Support und Dashboards. example: 43762 session_token: type: string description: >- 12-stelliger URL-sicherer Token, der den Endbenutzer autorisiert, auf den gehosteten Verifizierungsablauf unter `url` zuzugreifen. Gültig, bis die Sitzung abläuft. Behandeln Sie ihn wie ein Geheimnis — jeder, der ihn besitzt, kann den Verifizierungsablauf für diese Sitzung öffnen. example: 3FaJ9wLqX2Mz url: type: string format: uri description: >- Gehostete Verifizierungs-URL, zu der der Endbenutzer weitergeleitet werden soll. Die URL bettet das `session_token` ein und verwendet, sofern konfiguriert, Ihre White-Label-Domain. Wenn die Anfrage `language` enthält, enthält die URL ein Sprachpfadsegment – `https://verify.didit.me/{language}/session/{session_token}` (z. B. `/es/session/...`); ohne `language` wird das Segment weggelassen. example: https://verify.didit.me/session/3FaJ9wLqX2Mz vendor_data: type: string nullable: true description: >- Kennung, die Sie in der Anfrage übergeben haben, um die Sitzung mit einem Benutzer oder Unternehmen in Ihrem eigenen System zu verknüpfen. Wird unverändert zurückgegeben. Null, wenn nicht angegeben. example: user-123 metadata: description: >- Beliebige JSON-Payload, die Sie bei der Erstellung mit der Sitzung gespeichert haben. Wird unverändert zurückgegeben – welcher JSON-Wert auch immer gesendet wurde (Objekt, String, Zahl, Array), wird so belassen, obwohl ein JSON-Objekt empfohlen wird. Für den Endbenutzer nicht sichtbar. In Antworten immer vorhanden; `null`, wenn bei der Erstellung nicht angegeben. example: user_type: premium account_id: ABC123 tags: type: array items: type: string description: Die Tags der Sitzung, nach Namen. example: - VIP - ONBOARDING Q4 status: type: string enum: - Not Started - In Progress - Approved - Declined - In Review - Expired - Abandoned - Kyc Expired - Resubmitted - Awaiting User description: >- Aktueller Status der Sitzung. Neu erstellte Sitzungen geben `Not Started` zurück. Falls für dieselben `vendor_data` in der neuesten veröffentlichten Version des Workflows bereits eine nicht abgeschlossene Sitzung existierte, spiegelt der zurückgegebene Status diese bestehende Sitzung wider. example: Not Started callback: type: string format: uri nullable: true description: >- Endgültige Weiterleitungs-URL, zu der der Benutzer nach Abschluss des Ablaufs weitergeleitet wird. Didit hängt `?verificationSessionId={session_id}&status={status}` an diese URL an. Fällt auf die im Workflow konfigurierte Callback-URL zurück, wenn sie nicht in der Anfrage angegeben ist; `null`, wenn keine von beiden festgelegt ist. Wenn die Anwendung erlaubte Domains konfiguriert hat und diese URL eine Web-URL außerhalb dieser ist (beispielsweise ein Workflow-Standard, der vor der Änderung der Liste festgelegt wurde), leitet der gehostete Ablauf den Benutzer nicht dorthin weiter. example: https://example.com/verification/callback workflow_id: type: string format: uuid description: >- Stabiler Identifikator des Workflows, auf dem diese Sitzung läuft. Immer der stabile Gruppenidentifikator des Workflows – selbst wenn Sie in der Anfrage auf eine bestimmte UUID einer Workflow-Version verwiesen haben (abwärtskompatibles Nachschlagen), enthält die Antwort die stabile `workflow_id`. Verwenden Sie sie, um die Sitzung mit dem Workflow zu korrelieren, den Sie in der Console konfiguriert haben. example: 11111111-2222-3333-4444-555555555555 workflow_version: type: integer description: >- Versionsnummer der veröffentlichten Workflow-Version, an die die Sitzung bei der Erstellung gebunden wurde. Didit löst `workflow_id` bei der Sitzungserstellung in die neueste veröffentlichte Version des Workflows auf, und die Sitzung verwendet diese Version weiterhin, selbst wenn der Workflow später erneut veröffentlicht wird. example: 3 examples: KYC session: summary: KYC-Sitzung erstellt value: session_id: 11111111-2222-3333-4444-555555555555 session_number: 43762 session_token: 3FaJ9wLqX2Mz url: https://verify.didit.me/en/session/3FaJ9wLqX2Mz vendor_data: user-123 metadata: user_type: premium account_id: ABC123 status: Not Started workflow_id: 11111111-2222-3333-4444-555555555555 workflow_version: 3 callback: https://example.com/verification/callback KYB session: summary: KYB-Sitzung erstellt value: session_id: 22222222-3333-4444-5555-666666666666 session_number: 43763 session_token: Yk7pQ2vN8aBc url: https://verify.didit.me/en/session/Yk7pQ2vN8aBc vendor_data: company-acme-001 metadata: tier: enterprise status: Not Started workflow_id: 33333333-4444-5555-6666-777777777777 workflow_version: 1 callback: https://example.com/kyb/callback '400': description: >- Ungültige Anfrage – die Payload hat die Validierung nicht bestanden (fehlende oder unbekannte `workflow_id`, ungültige `language`, gesperrte `vendor_data`, fehlerhaftes `portrait_image`, `address` ohne `country`/`poa_country`, ungültiges `sandbox_scenario`, `sign`-Dokumente, Felder oder Werte, die der E-Signatur-Schritt des Workflows ablehnt, wie z. B. `signature_document_not_supported`, `signature_document_conversion_failed`, `field_anchor_not_found` oder `field_value_missing` usw.) oder Ihre Organisation hat nicht genügend Credits, um die Sitzung zu starten. Der Body ist ein Objekt mit dem fehlerhaften Feldnamen als Schlüssel (oder `detail` bei Fehlern, die kein Feld betreffen). Die Werte sind ein **Array von Strings** bei Eingabevalidierungsfehlern (z. B. fehlendes Pflichtfeld, ungültige Sprache, zu großes Porträtbild) und ein **einfacher String** bei Fehlern, die während der Sitzungserstellung erkannt wurden (unbekannte `workflow_id`, gesperrte `vendor_data`, kein Referenzgesicht für einen Face-Match-Workflow verfügbar). Behandeln Sie beide Formen. content: application/json: schema: type: object additionalProperties: true properties: detail: type: string description: >- Lesbare Fehlermeldung für Fehler, die sich nicht auf ein bestimmtes Feld beziehen (z. B. unzureichende Credits). Fehler auf Feldebene verwenden stattdessen den Feldnamen als Schlüssel mit einem String oder einem Array aus Strings als Wert. example: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me examples: Missing workflow_id: summary: Erforderliches Feld weggelassen (Array-von-Strings-Format) value: workflow_id: - This field is required. Invalid workflow_id: summary: Unbekannte workflow_id (reines Zeichenfolgenformat) value: workflow_id: Invalid workflow_id. Insufficient credits: summary: Die Organisation hat keine Credits mehr value: detail: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me Blocklisted vendor_data: summary: vendor_data steht auf der Sperrliste value: vendor_data: >- This user or business has been blocked and cannot create new verification sessions. Portrait image too large: summary: portrait_image besteht die Größenvalidierung nicht value: portrait_image: - Image size exceeds 2MB. No stored face for vendor_data: summary: >- Gesichtsabgleich-Workflow ohne portrait_image und ohne gespeichertes Gesicht für den vendor_data-Benutzer value: portrait_image: >- No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first. Portrait image required without vendor_data: summary: >- Gesichtsabgleich-Workflow ohne portrait_image und ohne vendor_data value: portrait_image: >- A portrait image is required to perform face match for this workflow. Send a portrait_image, or provide the vendor_data of a user with a previously stored face image to reuse it. '403': description: >- Authentifizierung oder Autorisierung fehlgeschlagen. Ein falscher, widerrufener oder abgelaufener Schlüssel gibt `401` zurück. Der Endpoint gibt `403` zurück, wenn der `x-api-key`-Header fehlt oder der API-Schlüssel gültig ist, der Client jedoch keine Berechtigung zum Erstellen von Sitzungen in dieser Anwendung hat (zum Beispiel wenn der API-Schlüssel zu einer anderen Organisation gehört). Diese Fehler teilen sich den Body `{"detail": "You do not have permission to perform this action."}`. Überprüfen Sie, ob der `x-api-key`-Header vorhanden ist und zur vorgesehenen Anwendung gehört, rufen Sie den API-Schlüssel der Anwendung bei Bedarf erneut über die [Auth API](/de/auth-api/get-credentials) ab und versuchen Sie es erneut. **Gelöschte Anwendung:** Für einige Minuten nach dem Löschen einer Anwendung kann eine Anfrage, die mit einem ihrer API-Schlüssel gestellt wird, mit `{"detail": "This application was deleted.", "code": "application_deleted"}` antworten. Versuchen Sie es nicht erneut: Die Anwendung und ihre API-Schlüssel existieren nicht mehr. Nach diesen wenigen Minuten wird der Schlüssel wie jeder andere ungültige Schlüssel abgewiesen. content: application/json: schema: type: object properties: detail: type: string example: You do not have permission to perform this action. code: type: string description: >- Maschinenlesbarer Grund, nur bei bestimmten Fehlern vorhanden. `application_deleted`: Der API-Schlüssel gehört zu einer Anwendung, die gelöscht wurde. example: application_deleted required: - detail examples: Missing or invalid API key: summary: Kein `x-api-key`-Header oder ungültiger API-Schlüssel value: detail: You do not have permission to perform this action. No permission: summary: Client kann keine Sitzungen erstellen value: detail: You do not have permission to perform this action. Application deleted: summary: API-Schlüssel einer gelöschten Anwendung value: detail: This application was deleted. code: application_deleted '429': description: >- Rate-Limit überschritten – mehr als 600 Anfragen zur Sitzungserstellung in einem 60-Sekunden-Fenster von demselben API-Schlüssel / derselben IP. Prüfen Sie `Retry-After` und warten Sie vor einem Wiederholungsversuch ab. **Hinweis:** Der Quellcode definiert neben `PAID_SESSION_RATE_LIMIT=600` (`sessions/serializers/session.py`) auch ein `FREE_SESSION_RATE_LIMIT` von 10 Aufrufen/Minute, diese Obergrenze für das kostenlose Kontingent wird jedoch **nicht auf diesen V3-Endpoint angewendet** – die Rate-Limit-Middleware erzwingt das `SESSION_CREATE_RATE_LIMIT` von 600/Min unabhängig vom Tarif. 600/Min ist das einzige Limit, das Sie hier erreichen können. headers: Retry-After: description: >- Sekunden, die der Aufrufer warten muss, bevor er die Anfrage wiederholt. schema: type: integer minimum: 1 example: 42 X-RateLimit-Limit: description: >- Maximale Anzahl an Anfragen, die im aktuellen 60-Sekunden-Fenster für das überschrittene Limit zulässig sind (600 für session-create). Fehlt bei der Sandbox-Kontingent-Variante. schema: type: integer example: 600 X-RateLimit-Remaining: description: >- Anzahl der im aktuellen Zeitfenster für das überschrittene Limit noch zulässigen Anfragen. Fehlt bei der Sandbox-Kontingent-Variante. schema: type: integer minimum: 0 example: 0 X-RateLimit-Reset: description: >- UTC-Epochensekunden, zu denen das aktuelle Rate-Limit-Fenster zurückgesetzt wird. Fehlt bei der Variante sandbox-quota. schema: type: integer minimum: 0 example: 1747497600 content: application/json: schema: type: object properties: detail: type: string description: >- Lesbare Erklärung der Rate-Limit-Überschreitung. Verwenden Sie diese Meldung, um zu unterscheiden, welches der drei Limits erreicht wurde. example: >- Session creation rate limit exceeded. You can make up to 600 requests per minute. examples: Session-create limit: summary: Mehr als 600 Anfragen zur Sitzungserstellung pro Minute value: detail: >- Session creation rate limit exceeded. You can make up to 600 requests per minute. Sandbox session quota: summary: >- Sandbox-Anwendung hat 500 Sitzungen in 24 Stunden überschritten value: detail: >- Sandbox session quota exceeded (500 sessions per 24h). Wait for the window to reset. Expected available in 3600 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/session/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "workflow_id": "11111111-2222-3333-4444-555555555555", "vendor_data": "user-123", "callback": "https://example.com/verification/callback", "callback_method": "both", "metadata": {"user_type": "premium", "account_id": "ABC123"}, "language": "en", "contact_details": { "email": "john.doe@example.com", "send_notification_emails": true, "email_lang": "en", "phone": "+14155552671" }, "expected_details": { "first_name": "John", "last_name": "Doe", "date_of_birth": "1990-05-15", "id_country": "USA", "expected_document_types": ["P", "ID"] } }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.sessions.create( workflow_id="11111111-2222-3333-4444-555555555555", vendor_data="user-123", callback="https://example.com/verification/callback", callback_method="both", metadata={"user_type": "premium", "account_id": "ABC123"}, language="en", contact_details={ "email": "john.doe@example.com", "send_notification_emails": True, "email_lang": "en", "phone": "+14155552671", }, expected_details={ "first_name": "John", "last_name": "Doe", "date_of_birth": "1990-05-15", "nationality": "USA", "id_country": "USA", "expected_document_types": ["P", "ID"], }, ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.sessions.create({ workflow_id: "11111111-2222-3333-4444-555555555555", vendor_data: "user-123", callback: "https://example.com/verification/callback", callback_method: "both", metadata: { user_type: "premium", account_id: "ABC123" }, language: "en", contact_details: { email: "john.doe@example.com", send_notification_emails: true, email_lang: "en", phone: "+14155552671", }, expected_details: { first_name: "John", last_name: "Doe", date_of_birth: "1990-05-15", nationality: "USA", id_country: "USA", expected_document_types: ["P", "ID"], }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{\n\tWorkflowID: \"11111111-2222-3333-4444-555555555555\",\n\tVendorData: didit.String(\"user-123\"),\n\tCallback: didit.String(\"https://example.com/verification/callback\"),\n\tCallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod(\"both\")),\n\tMetadata: didit.Some[any](map[string]any{\"user_type\": \"premium\", \"account_id\": \"ABC123\"}),\n\tLanguage: didit.Some(didit.SessionsCreateParamsLanguage(\"en\")),\n\tContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{\n\t\tEmail: didit.String(\"john.doe@example.com\"),\n\t\tSendNotificationEmails: didit.Bool(true),\n\t\tEmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang(\"en\")),\n\t\tPhone: didit.String(\"+14155552671\"),\n\t}),\n\tExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{\n\t\tFirstName: didit.String(\"John\"),\n\t\tLastName: didit.String(\"Doe\"),\n\t\tDateOfBirth: didit.String(\"1990-05-15\"),\n\t\tNationality: didit.String(\"USA\"),\n\t\tIDCountry: didit.String(\"USA\"),\n\t\tExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{\"P\", \"ID\"}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: |- import java.time.LocalDate; import java.util.List; import java.util.Map; import me.didit.Didit; import me.didit.types.SessionsCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.sessions().create(SessionsCreateParams.builder() .workflowId("11111111-2222-3333-4444-555555555555") .vendorData("user-123") .callback("https://example.com/verification/callback") .callbackMethod(SessionsCreateParams.CallbackMethod.of("both")) .metadata(Map.of("user_type", "premium", "account_id", "ABC123")) .language(SessionsCreateParams.Language.of("en")) .contactDetails(SessionsCreateParams.ContactDetails.builder() .email("john.doe@example.com") .sendNotificationEmails(true) .emailLang(SessionsCreateParams.ContactDetails.EmailLang.of("en")) .phone("+14155552671") .build()) .expectedDetails(SessionsCreateParams.ExpectedDetails.builder() .firstName("John") .lastName("Doe") .dateOfBirth(LocalDate.parse("1990-05-15")) .nationality("USA") .idCountry("USA") .expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("P"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("ID"))) .build()) .build()); System.out.println(result); - lang: php label: PHP source: |- sessions->create([ 'workflow_id' => '11111111-2222-3333-4444-555555555555', 'vendor_data' => 'user-123', 'callback' => 'https://example.com/verification/callback', 'callback_method' => 'both', 'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'], 'language' => 'en', 'contact_details' => [ 'email' => 'john.doe@example.com', 'send_notification_emails' => true, 'email_lang' => 'en', 'phone' => '+14155552671', ], 'expected_details' => [ 'first_name' => 'John', 'last_name' => 'Doe', 'date_of_birth' => '1990-05-15', 'nationality' => 'USA', 'id_country' => 'USA', 'expected_document_types' => ['P', 'ID'], ], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.sessions.create( workflow_id: "11111111-2222-3333-4444-555555555555", vendor_data: "user-123", callback: "https://example.com/verification/callback", callback_method: "both", metadata: { user_type: "premium", account_id: "ABC123" }, language: "en", contact_details: { email: "john.doe@example.com", send_notification_emails: true, email_lang: "en", phone: "+14155552671", }, expected_details: { first_name: "John", last_name: "Doe", date_of_birth: "1990-05-15", nationality: "USA", id_country: "USA", expected_document_types: ["P", "ID"], } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Sessions.CreateAsync(new SessionsCreateParams { WorkflowId = "11111111-2222-3333-4444-555555555555", VendorData = "user-123", Callback = "https://example.com/verification/callback", CallbackMethod = new SessionsCreateParamsCallbackMethod("both"), Metadata = new Dictionary { ["user_type"] = "premium", ["account_id"] = "ABC123" }, Language = new SessionsCreateParamsLanguage("en"), ContactDetails = new SessionsCreateParamsContactDetails { Email = "john.doe@example.com", SendNotificationEmails = true, EmailLang = new SessionsCreateParamsContactDetailsEmailLang("en"), Phone = "+14155552671", }, ExpectedDetails = new SessionsCreateParamsExpectedDetails { FirstName = "John", LastName = "Doe", DateOfBirth = "1990-05-15", Nationality = "USA", IdCountry = "USA", ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { "P", "ID" }, }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: SessionSignDocument: type: object required: - file_name - content_base64 properties: title: type: string minLength: 1 maxLength: 255 description: Dem Unterzeichner angezeigter Titel. Standardmäßig `file_name`. file_name: type: string minLength: 1 maxLength: 255 description: Dateiname, der auf `.pdf` oder `.docx` endet. content_base64: type: string format: byte description: >- Die Datei, Base64-kodiert. Ein PDF kann bis zu 20 MB und 100 Seiten umfassen, ohne Passwort, Skripte oder angehängte Dateien. Eine Word-Datei (`.docx`) kann bis zu 20 MB umfassen und wird während der Anfrageausführung in maximal 25 Sekunden in ein PDF konvertiert; für das PDF gelten dann dieselben Limits. Bis zu 5 Word-Dateien pro Sitzung. Eine Word-Datei mit Makros, nachverfolgten Änderungen, Links zu externen Inhalten oder eingebetteten Objekten wird mit `signature_document_not_supported` abgelehnt, und eine Datei, die nicht konvertiert werden kann, gibt `signature_document_conversion_failed` zurück, jeweils mit einem `reason`. fields: type: array description: >- Optionale Felder, die auf diesem Dokument platziert werden sollen, bis zu 200. Seiten und Positionen beziehen sich auf das PDF bzw. auf das konvertierte PDF bei einer Word-Datei. Ohne Felder liest der Unterzeichner das Dokument und stimmt ihm zu. items: $ref: '#/components/schemas/SignatureField' maxItems: 200 SignatureField: type: object description: >- Ein Feld, das auf einem Sitzungsdokument platziert werden soll: welcher Unterzeichner es ausfüllt, wie und wo. Geben Sie entweder eine Position (`page`, `x`, `y`, `width` und `height`) oder einen `anchor` an. Positionen sind Anteile der Seite, wie sie angezeigt wird, ausgehend von der oberen linken Ecke, gerundet auf 4 Dezimalstellen, und das Feld muss innerhalb der Seite liegen. Ein Dokument fasst bis zu 200 Felder und ein Unterzeichner bis zu 500, und jede Rolle mit Feldern auf einem Dokument benötigt dort ein `signature`- oder `initials`-Feld. Siehe [Felder auf dem Dokument](/de/core-technology/electronic-signature/overview#felder-auf-dem-dokument). required: - key - type properties: key: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ description: >- Benennt das Feld in den Ergebnissen und in `sign.field_values`. Eindeutig innerhalb des Dokuments. type: type: string enum: - signature - initials - full_name - date_signed - text - checkbox - email - data description: >- Was das Feld enthält. Der Unterzeichner verwendet seine hinterlegte `signature` und `initials`, tippt `text` ein, hakt eine `checkbox` an und gibt eine `email` ein, wenn die Sitzung keine verifizierte E-Mail-Adresse hat. Didit füllt `full_name` (der verifizierte Name), `date_signed` (das Datum der Unterzeichnung in der Zeitzone des Unterzeichners), `data` (aus `prefill`) und eine verifizierte `email` aus und zeigt sie schreibgeschützt an. Es gibt keinen Datepicker-Typ: Verwenden Sie `text`. role: type: string enum: - verified_person - legal_representative - key_people description: >- Wer das Feld ausfüllt, mit den Werten von `signature_signer`. Ein Schritt füllt und stempelt nur die Felder seines eigenen Unterzeichners aus. Standardmäßig der Unterzeichner des Schritts. page: type: integer minimum: 1 description: >- Seitenzahl, von 1 bis zur Gesamtseitenzahl des Dokuments. Bei einem Word-Dokument eine Seite des konvertierten PDFs. x: type: number minimum: 0 maximum: 1 description: Linke Kante als Bruchteil der Seitenbreite. 'y': type: number minimum: 0 maximum: 1 description: Oberer Rand als Bruchteil der Seitenhöhe. width: type: number minimum: 0.02 maximum: 1 description: >- Breite als Bruchteil der Seitenbreite. Eine Signatur ist mindestens `0.12` breit. height: type: number minimum: 0.012 maximum: 1 description: >- Höhe als Bruchteil der Seitenhöhe. Eine Signatur ist mindestens `0.035` hoch. anchor: $ref: '#/components/schemas/SignatureFieldAnchor' required: type: boolean description: >- `signature` and `initials` are required unless you set `false`. `full_name`, `date_signed` and `data` are always required. The signer can't finish a document until its required fields have a value, and a required checkbox must be ticked. label: type: string minLength: 1 maxLength: 80 description: >- Wird dem Unterzeichner und in den Ergebnissen angezeigt. Standardwert richtet sich nach dem Typ. placeholder: type: string nullable: true maxLength: 80 description: Nur `text` und `email`. validation: $ref: '#/components/schemas/SignatureFieldValidation' prefill: type: string nullable: true description: >- Woher der Wert stammt: `identity.full_name`, `identity.first_name`, `identity.last_name`, `identity.date_of_birth` (`DD/MM/YYYY`), `identity.nationality`, `identity.document_number`, `identity.document_type`, `identity.issuing_country`, `identity.address`, `contact.email`, `contact.phone`, `company.name`, `company.registration_number`, `company.address`, `company.country` (KYB), `session.vendor_data`, `metadata.` (ein Schlüssel der `metadata` der Sitzung) oder `api.` (ein Schlüssel von `sign.field_values`). Erforderlich für `data`. `full_name` verwendet immer `identity.full_name` und `email` verwendet `contact.email`. Die Werte der Felder `data`, `full_name` und der verifizierten `email` werden festgelegt, wenn der Unterzeichner mit dem Unterzeichnen beginnt. editable_when_prefilled: type: boolean default: false description: >- Nur `text` und `email`: Der Unterzeichner kann einen vorausgefüllten Wert ändern. checked_by_default: type: boolean default: false description: 'Nur `checkbox`: Das Kästchen ist anfangs angehakt.' date_format: type: string enum: - DD/MM/YYYY - MM/DD/YYYY - YYYY-MM-DD - D MMMM YYYY default: DD/MM/YYYY description: Nur `date_signed`. SignatureFieldAnchor: type: object description: >- Platziert ein Feld anhand einer Textstelle im Dokument anstelle einer Position. Didit entfernt den Text nicht aus dem PDF; schreiben Sie ihn daher in derselben Farbe wie den Seitenhintergrund. Wenn der Text nicht gefunden wird, gibt der Aufruf `400` mit `field_anchor_not_found` zurück. Siehe [Felder über Ankertext platzieren](/de/sessions-api/create-session#felder-über-ankertext-platzieren). required: - text properties: text: type: string minLength: 1 maxLength: 64 description: >- Im Dokument gesuchter Text. Bei einer Word-Datei im konvertierten PDF. occurrence: type: string enum: - first - all default: first description: >- `all` fügt pro Übereinstimmung ein Feld ein; die Schlüssel nach dem ersten erhalten `_2`, `_3` und so weiter. offset_x: type: number description: >- Am linken Rand des Texts hinzugefügt, als Bruchteil der Seitenbreite. offset_y: type: number description: Am oberen Rand des Texts hinzugefügt, als Bruchteil der Seitenhöhe. width: type: number minimum: 0.02 maximum: 1 description: Breite des Felds als Bruchteil der Seitenbreite. height: type: number minimum: 0.012 maximum: 1 description: Höhe des Felds als Bruchteil der Seitenhöhe. SignatureFieldValidation: type: object nullable: true description: >- Regeln für den Wert eines `text`-Felds. Die Konsolenvorschau, der Signatur-Ablauf und die API wenden dieselben Regeln an. properties: kind: type: string enum: - any - letters - number - email - pattern description: >- `letters`: Buchstaben in jedem Schriftsystem, Leerzeichen, Bindestriche und Apostrophe. `number`: Ziffern mit einem optionalen Dezimaltrennzeichen. `pattern`: Der Wert muss mit `pattern` übereinstimmen. min_length: type: integer minimum: 0 maximum: 500 description: Von `0` bis `max_length`. max_length: type: integer minimum: 1 maximum: 500 default: 120 pattern: type: string nullable: true minLength: 1 maxLength: 200 description: >- Erforderlich bei `kind: "pattern"`. Ein regulärer Ausdruck, mit dem der gesamte Wert übereinstimmen muss. Lookarounds und Backreferences werden nicht unterstützt. message: type: string nullable: true maxLength: 120 description: Wird dem Unterzeichner anstelle des Standardfehlers angezeigt. 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.