Sitzung erstellen API: KYC/KYB-Verifizierung starten

cURL

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"]
    }
  }'

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)

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);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{
	WorkflowID:     "11111111-2222-3333-4444-555555555555",
	VendorData:     didit.String("user-123"),
	Callback:       didit.String("https://example.com/verification/callback"),
	CallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod("both")),
	Metadata:       didit.Some[any](map[string]any{"user_type": "premium", "account_id": "ABC123"}),
	Language:       didit.Some(didit.SessionsCreateParamsLanguage("en")),
	ContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{
		Email:                  didit.String("john.doe@example.com"),
		SendNotificationEmails: didit.Bool(true),
		EmailLang:              didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang("en")),
		Phone:                  didit.String("+14155552671"),
	}),
	ExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{
		FirstName:             didit.String("John"),
		LastName:              didit.String("Doe"),
		DateOfBirth:           didit.String("1990-05-15"),
		Nationality:           didit.String("USA"),
		IDCountry:             didit.String("USA"),
		ExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{"P", "ID"}),
	}),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

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);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$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'],
    ],
]);
print_r($result->toArray());

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

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<string, object> { ["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));

{
  "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"
}

POST

session

cURL

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"]
    }
  }'

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)

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);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{
	WorkflowID:     "11111111-2222-3333-4444-555555555555",
	VendorData:     didit.String("user-123"),
	Callback:       didit.String("https://example.com/verification/callback"),
	CallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod("both")),
	Metadata:       didit.Some[any](map[string]any{"user_type": "premium", "account_id": "ABC123"}),
	Language:       didit.Some(didit.SessionsCreateParamsLanguage("en")),
	ContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{
		Email:                  didit.String("john.doe@example.com"),
		SendNotificationEmails: didit.Bool(true),
		EmailLang:              didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang("en")),
		Phone:                  didit.String("+14155552671"),
	}),
	ExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{
		FirstName:             didit.String("John"),
		LastName:              didit.String("Doe"),
		DateOfBirth:           didit.String("1990-05-15"),
		Nationality:           didit.String("USA"),
		IDCountry:             didit.String("USA"),
		ExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{"P", "ID"}),
	}),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

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);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$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'],
    ],
]);
print_r($result->toArray());

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

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<string, object> { ["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));

{
  "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"
}

Unterstützung für KYC und KYB

Ein 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

Benutzerverifizierung (KYC)
Unternehmensverifizierung (KYB)

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):

{
  "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"
}

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):

{
  "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-Dokumente

Wenn der Workflow einen E-Signatur-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.

{
  "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, 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`. `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 platzieren

Anstelle 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.<key> ist, sowohl bei Workflow-Dokumenten als auch bei Sitzungsdokumenten. Es ist ein Objekt, dessen Schlüssel die <key>-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.

{
  "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.<key>` keinen Wert hat.
`field_value_invalid`	Ein Wert, der die Validierung seines Feldes nicht besteht.

Fehler und wiederholte Aufrufe

Eine 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.
Ein Feld ungültig ist, sein Anker nicht gefunden wird (field_anchor_not_found) oder ein Feldwert 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-Szenarien

In 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:

{
  "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.

`vendor_data` verknüpft die Sitzung mit einer Entität

Bei KYC-Workflows wird eine Verknüpfung mit einer Benutzer-Entität hergestellt. Existiert der Benutzer nicht, wird er automatisch angelegt.
Bei KYB-Workflows wird eine Verknüpfung mit einer Unternehmens-Entität hergestellt. Ist sie neu, wird sie automatisch angelegt.

Mehr dazu unter Verknüpfung von Vendor-Daten.

Biometrische Einwilligung in Illinois, Texas und Colorado

Die 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.

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 Verifizierung

Teilen Sie dem Benutzer mit, dass Ihr Unternehmen die Verifizierung anfordert und dass Didit als Verifizierungsdienstleister bzw. Auftragsverarbeiter den Ablauf bereitstellt.
Verlinken Sie auf Ihre Datenschutzerklärung und alle für den Ablauf geltenden rechtlichen Bedingungen des Verantwortlichen.
Verlinken Sie auf den Datenschutzhinweis zur Verifizierung und die Nutzungsbedingungen für Endbenutzer zur Identitätsverifizierung von Didit.
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.
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.
Bewahren Sie Ihren eigenen Nachweis über Hinweis- und Einwilligungstext, Zeitstempel und zugehörige Metadaten auf, sofern Ihre Rechtsabteilung einen Prüfpfad verlangt.

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.

Autorisierungen

x-api-key

string

header

erforderlich

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.

Body

application/json

workflow_id

string<uuid>

erforderlich

Stabiler Identifikator des Workflows, der definiert, welche Verifizierungsschritte die Sitzung ausführt. Workflows werden auf der Seite Workflows der Console erstellt und verwaltet. Die workflow_id legt zudem implizit fest, ob es sich bei der Sitzung um KYC oder KYB handelt.

Beispiel:

"11111111-2222-3333-4444-555555555555"

vendor_data

string

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.

Beispiel:

"user-123"

multi_account_segment

string

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.

Maximum string length: 64

Beispiel:

"business-accounts"

callback

string

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.

Beispiel:

"https://example.com/verification/callback"

callback_method

enum<string>

Standard:initiator

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.

Verfügbare Optionen:

initiator,

completer,

both

Beispiel:

"both"

metadata

any

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.

Beispiel:

{
  "user_type": "premium",
  "account_id": "ABC123"
}

Antwort

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.

session_id

string<uuid>

erforderlich

Eindeutige Kennung der Verifizierungssitzung. Verwenden Sie diese ID beim Aufruf von GET /v3/session/{sessionId}/decision/.

Beispiel:

"11111111-2222-3333-4444-555555555555"

session_number

integer

erforderlich

Fortlaufende, lesbare Nummer, die der Sitzung innerhalb Ihrer Anwendung zugewiesen wurde. Nützlich für Support und Dashboards.

Beispiel:

43762

session_token

string

erforderlich

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.

Beispiel:

"3FaJ9wLqX2Mz"

url

string<uri>

erforderlich

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.

Beispiel:

"https://verify.didit.me/session/3FaJ9wLqX2Mz"

vendor_data

string | null

erforderlich

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.

Beispiel:

"user-123"

metadata

any

erforderlich

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.

Beispiel:

{
  "user_type": "premium",
  "account_id": "ABC123"
}

status

enum<string>

erforderlich

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.

Verfügbare Optionen:

Not Started,

In Progress,

Approved,

Declined,

In Review,

Expired,

Abandoned,

Kyc Expired,

Resubmitted,

Awaiting User

Beispiel:

"Not Started"

callback

string<uri> | null

erforderlich

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.

Beispiel:

"https://example.com/verification/callback"

workflow_id

string<uuid>

erforderlich

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.

Beispiel:

"11111111-2222-3333-4444-555555555555"

workflow_version

integer

erforderlich

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.

Beispiel:

3

​Unterstützung für KYC und KYB

​Beispiele

​E-Signatur-Dokumente

​Felder über Ankertext platzieren

​Feldwerte

​Fehler und wiederholte Aufrufe

​Tests mit Sandbox-Szenarien

​vendor_data verknüpft die Sitzung mit einer Entität

​Biometrische Einwilligung in Illinois, Texas und Colorado

​Wichtig: Offenlegung und Einwilligung erfolgen weiterhin in Ihrem Produkt

​Empfohlene Checkliste vor der Verifizierung

Autorisierungen

Body

Antwort

Unterstützung für KYC und KYB

Beispiele

E-Signatur-Dokumente

Felder über Ankertext platzieren

Feldwerte

Fehler und wiederholte Aufrufe

Tests mit Sandbox-Szenarien

`vendor_data` verknüpft die Sitzung mit einer Entität

Biometrische Einwilligung in Illinois, Texas und Colorado

Wichtig: Offenlegung und Einwilligung erfolgen weiterhin in Ihrem Produkt

Empfohlene Checkliste vor der Verifizierung