Benutzer anlegen API: Vendor-User-Entität

curl

curl -X POST 'https://verification.didit.me/v3/users/create/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"vendor_data": "user-abc-123", "full_name": "John Doe"}'

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.users.create({
  vendor_data: "user-abc-123",
  full_name: "John Doe",
});
console.log(result);

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

result, err := client.Users.Create(ctx, didit.UsersCreateParams{
	VendorData: "user-abc-123",
	FullName:   didit.String("John Doe"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.UsersCreateParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.users().create(UsersCreateParams.builder()
        .vendorData("user-abc-123")
        .fullName("John Doe")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

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

$result = $didit->users->create([
    'vendor_data' => 'user-abc-123',
    'full_name' => 'John Doe',
]);
print_r($result->toArray());

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Users.CreateAsync(new UsersCreateParams
{
    VendorData = "user-abc-123",
    FullName = "John Doe",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418",
  "vendor_data": "user-abc-123",
  "display_name": null,
  "full_name": "John Doe",
  "date_of_birth": null,
  "effective_name": "John Doe",
  "status": "ACTIVE",
  "metadata": {},
  "portrait_image_url": null,
  "session_count": 0,
  "approved_count": 0,
  "declined_count": 0,
  "in_review_count": 0,
  "issuing_states": [],
  "approved_emails": [],
  "approved_phones": [],
  "features": {},
  "features_list": [],
  "last_session_at": null,
  "last_activity_at": "2025-06-15T10:30:00Z",
  "first_session_at": null,
  "tags": [],
  "comments": [],
  "created_at": "2025-06-15T10:30:00Z",
  "updated_at": "2025-06-15T10:30:00Z",
  "verification_link": null
}

POST

users

create

curl

curl -X POST 'https://verification.didit.me/v3/users/create/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"vendor_data": "user-abc-123", "full_name": "John Doe"}'

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.users.create({
  vendor_data: "user-abc-123",
  full_name: "John Doe",
});
console.log(result);

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

result, err := client.Users.Create(ctx, didit.UsersCreateParams{
	VendorData: "user-abc-123",
	FullName:   didit.String("John Doe"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.UsersCreateParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.users().create(UsersCreateParams.builder()
        .vendorData("user-abc-123")
        .fullName("John Doe")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

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

$result = $didit->users->create([
    'vendor_data' => 'user-abc-123',
    'full_name' => 'John Doe',
]);
print_r($result->toArray());

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Users.CreateAsync(new UsersCreateParams
{
    VendorData = "user-abc-123",
    FullName = "John Doe",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418",
  "vendor_data": "user-abc-123",
  "display_name": null,
  "full_name": "John Doe",
  "date_of_birth": null,
  "effective_name": "John Doe",
  "status": "ACTIVE",
  "metadata": {},
  "portrait_image_url": null,
  "session_count": 0,
  "approved_count": 0,
  "declined_count": 0,
  "in_review_count": 0,
  "issuing_states": [],
  "approved_emails": [],
  "approved_phones": [],
  "features": {},
  "features_list": [],
  "last_session_at": null,
  "last_activity_at": "2025-06-15T10:30:00Z",
  "first_session_at": null,
  "tags": [],
  "comments": [],
  "created_at": "2025-06-15T10:30:00Z",
  "updated_at": "2025-06-15T10:30:00Z",
  "verification_link": null
}

Überblick

Legt eine Benutzer-Entität explizit an, bevor eine Sitzung gestartet wird. Die zurückgegebene Entität erhält den Status ACTIVE, sofern Sie nichts anderes angeben. Optional sendet derselbe Aufruf der Person per E-Mail einen Verifizierungslink (siehe Verifizierungslink senden).

Wann Sie es verwenden

Metadaten vorab befüllen (Stufe, Registrierungsquelle, interne Tags), bevor sich der Kunde verifiziert.
Von einem anderen Anbieter migrieren: Bestehende Benutzerliste in Didit neu anlegen, damit Verlauf und Analysen von einer bekannten Basis aus starten.
Vertrauenswürdige Gesichter für Profile importieren: Zuerst den Benutzer anlegen, dann Gesicht eines Benutzers hochladen mit der zurückgegebenen didit_internal_id aufrufen.
Reine Transaktionsfälle: Einen Benutzer mit vendor_data registrieren, damit Sie Transaktionen einreichen können, ohne jemals eine Sitzung zur Benutzerverifizierung (KYC) durchzuführen.
Zur Verifizierung einladen: Person anlegen und ihr in einem Aufruf einen Verifizierungslink per E-Mail senden.

Kontaktdaten

Sie können die Kontaktdaten der Person zusammen mit den Profilfeldern senden. first_name und last_name werden mit einem Leerzeichen zu full_name verbunden, wenn Sie kein full_name senden. email und phone_number werden in metadata.contact gespeichert, country in metadata.address. country akzeptiert einen ISO-3166-Code, alpha-2 oder alpha-3 (ES oder ESP), und wird in Großbuchstaben gespeichert. Wenn die metadata, die Sie senden, bereits einen contact- oder address-Wert enthält, der kein JSON-Objekt ist, überschreibt Didit ihn nicht: Der Aufruf antwortet mit 400 für das Kontaktfeld, das einen JSON-Objektwert benötigt.

Verifizierungslink senden

Setzen Sie send_verification_link auf true, um die Person im selben Aufruf zur Verifizierung einzuladen. Didit erstellt für die Person eine Verifizierungssitzung im durch workflow_id angegebenen Workflow und sendet ihr den Link an email. Verwenden Sie language, um die Sprache der E-Mail festzulegen; ohne Angabe ist sie Englisch.

curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-abc-789",
    "first_name": "Julia",
    "last_name": "Martin",
    "email": "julia.martin@example.com",
    "send_verification_link": true,
    "workflow_id": "YOUR_WORKFLOW_ID",
    "language": "es"
  }'

email und workflow_id sind bei einem Link erforderlich, und der Workflow muss eine Person verifizieren: Ein Workflow für Unternehmensverifizierung (KYB) antwortet mit 400.
Die Sitzung durchläuft dieselben Prüfungen wie Sitzung erstellen. Ein vendor_data auf der Sperrliste oder zu wenige Credits führen zu 400.
Die Person und die Sitzung werden gemeinsam oder gar nicht angelegt. Schlägt eine Prüfung fehl, wird nichts geschrieben und keine E-Mail gesendet.
Die Antwort enthält verification_link mit session_id, session_number, status, url und workflow_id der Sitzung sowie der email, an die er gesendet wurde. Ohne Link ist verification_link null.

Hinweise

vendor_data ist Pflicht und muss je Anwendung eindeutig sein. Der Versuch, ein Duplikat anzulegen, gibt einen Konfliktfehler zurück. Verwenden Sie PATCH /v3/users/{vendor_data}/, um einen bestehenden Benutzer zu aktualisieren.
vendor_data hat ein festes Limit von 2000 Bytes (UTF-8-kodiert). Ein Wert, der dieses Limit überschreitet, führt zu einem Validierungsfehler mit 400, statt akzeptiert zu werden.
Felder, die normalerweise aus verifizierten Sitzungen abgeleitet werden (full_name, date_of_birth), können hier vorbelegt werden, können aber durch die erste genehmigte Sitzung zur Benutzerverifizierung (KYC) überschrieben werden.
Gesichtsbilder werden von diesem Endpoint nicht akzeptiert. Um ein vertrauenswürdiges importiertes Gesicht anzuhängen, verwenden Sie POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/, nachdem dieser Endpoint die didit_internal_id zurückgegeben hat.
Das Anlegen selbst sendet keinen Webhook. Spätere Änderungen am Benutzer senden user.data.updated oder user.status.updated.
Mit send_verification_link aktualisiert die neue Sitzung den Benutzer im selben Aufruf, was user.data.updated sendet.

Berechtigungen

Das primäre Secret und API-Schlüssel mit vollem Zugriff können diesen Endpoint immer aufrufen. Ein Schlüssel mit benutzerdefiniertem Zugriff benötigt Schreibzugriff auf Personen (users). Mit send_verification_link: true benötigt er außerdem Schreibzugriff auf Sitzungen, weil der Aufruf eine Sitzung erstellt und deren Link ausgibt. Ohne diesen Zugriff antwortet der Aufruf mit 403 und This API key has no write access to sessions., und nichts wird geschrieben. Ein Schlüssel, der auf bestimmte Workflows oder auf genehmigte Sitzungen beschränkt ist, kann diesen Endpoint nicht erreichen. Die Rollen und Berechtigungen der Konsole bestimmen, was ein Teammitglied in der Konsole tun darf. Sie werden für Anfragen mit API-Schlüsseln nicht ausgewertet.

Verwandte Seiten

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

vendor_data

string

erforderlich

Ihre eindeutige Kennung für diesen Benutzer (Freitext-String, KEINE UUID). Muss unter den Benutzern der Anwendung eindeutig sein; exakt wie übermittelt abgeglichen.

full_name

string | null

Vollständiger rechtlicher Name des Benutzers.

Maximum string length: 512

display_name

string | null

Benutzerfreundlicher Anzeigename, der in der Konsole angezeigt wird (hat für die UI-Anzeige Vorrang vor full_name).

Maximum string length: 255

date_of_birth

string<date> | null

Geburtsdatum im Format YYYY-MM-DD.

status

enum<string>

Standard:ACTIVE

Anfänglicher Lebenszyklusstatus. Standardmäßig ACTIVE.

Verfügbare Optionen:

ACTIVE,

FLAGGED,

BLOCKED

metadata

object | null

Beliebiges JSON-Objekt, das Sie an den Benutzer anhängen. Standardmäßig {}.

approved_emails

string[]

Vorab als vertrauenswürdig eingestufte E-Mail-Adressen für diesen Benutzer, z. B. ["john@example.com"].

approved_phones

string[]

Vorab als vertrauenswürdig eingestufte Telefonnummern für diesen Benutzer, z. B. ["+14155551234"].

issuing_states

string[]

Vorab erfasste Ausstellungsländer (ISO 3166-1 Alpha-3), z. B. ["USA"].

first_name

string

Vorname. Wenn full_name nicht gesendet wird, verbindet Didit first_name und last_name mit einem Leerzeichen zu full_name. Wird nicht als separates Feld zurückgegeben.

Maximum string length: 255

last_name

string

Nachname. Wird mit first_name zu full_name zusammengefügt, wenn full_name nicht übermittelt wird. Wird nicht als separates Feld zurückgegeben.

Maximum string length: 255

string<email>

Kontakt-E-Mail, gespeichert in metadata.contact.email (sie ersetzt eine email, die Sie innerhalb von metadata.contact senden). Erforderlich, wenn send_verification_link auf true gesetzt ist: Der Link wird an diese Adresse gesendet. Wenn metadata.contact kein JSON-Objekt ist, antwortet der Aufruf bei diesem Feld mit 400.

phone_number

string

Telefonnummer des Kontakts, gespeichert in metadata.contact.phone_number. Wenn metadata.contact kein JSON-Objekt ist, antwortet der Aufruf für dieses Feld mit 400.

Maximum string length: 32

country

string

Land als ISO-3166-Code, Alpha-2 oder Alpha-3 (ES oder ESP). Wird in Großbuchstaben in metadata.address.country gespeichert. Wenn metadata.address kein JSON-Objekt ist, antwortet der Aufruf für dieses Feld mit 400.

Maximum string length: 3

send_verification_link

boolean

Standard:false

Wenn true, erstellt Didit eine Verifizierungssitzung für die Person unter workflow_id und sendet ihr den Link per E-Mail an email. Erfordert email und workflow_id. Ein berechtigungsbeschränkter API-Schlüssel benötigt außerdem Schreibrechte für sessions.

workflow_id

string<uuid>

Der Workflow der Verifizierungssitzung. Erforderlich, wenn send_verification_link auf true gesetzt ist. Er muss eine Person verifizieren: Ein Workflow für Unternehmensverifizierung (KYB) wird abgelehnt. Andernfalls wird er ignoriert.

language

string

Sprache der Verifizierungs-E-Mail als Code einer unterstützten Sprache. Wenn nicht angegeben, wird Englisch verwendet. Wird ignoriert, wenn send_verification_link nicht true ist.

Maximum string length: 10

Antwort

Benutzer erstellt. Der vollständige Benutzerdatensatz (gleiches Format wie bei Get User), plus verification_link: die Verifizierungssitzung, die Didit per E-Mail gesendet hat, wenn send_verification_link auf true gesetzt war, andernfalls null.

Vollständige Benutzerdetails. Erweitert UserListItem um Metadaten, Kommentare und updated_at.

verification_link

object | null

erforderlich

Die Verifizierungssitzung, die Didit erstellt und der Person per E-Mail gesendet hat. Immer vorhanden: null, wenn send_verification_link nicht true war.

Show child attributes

didit_internal_id

string<uuid>

Didits stabile interne UUID für diesen Benutzer.

vendor_data

string | null

Ihre eindeutige Kennung für diesen Benutzer (beim Erstellen von Sitzungen übergeben). Dies kann null sein, wenn keine Vendor-Kennung angegeben wurde.

display_name

string | null

Von Ihnen festgelegter benutzerdefinierter Anzeigename

full_name

string | null

Aus verifizierten Dokumenten extrahierter vollständiger Name

date_of_birth

string<date> | null

effective_name

string | null

Bester verfügbarer Name: display_name, falls gesetzt, andernfalls full_name

status

enum<string>

Lebenszyklusstatus des Benutzerdatensatzes (KEIN Sitzungsstatus). ACTIVE ist der Standard, FLAGGED markiert den Benutzer für manuelle Prüfung, BLOCKED verhindert neue Sitzungen für dieses vendor_data.

Verfügbare Optionen:

ACTIVE,

FLAGGED,

BLOCKED

portrait_image_url

string | null

Vorsignierte URL des Porträtfotos des Benutzers (läuft nach wenigen Stunden ab)

session_count

integer

Gesamtzahl der Verifizierungssitzungen für diesen Benutzer

approved_count

integer

Anzahl der genehmigten Sitzungen

declined_count

integer

Anzahl der abgelehnten Sitzungen

in_review_count

integer

Anzahl der Sitzungen in Prüfung

issuing_states

string[]

ISO 3166-1-Alpha-3-Codes der Ausstellungsländer, die auf den genehmigten Ausweisdokumenten dieses Benutzers gefunden wurden, z. B. ["USA", "ESP"]. Leeres Array, wenn keine vorhanden sind.

approved_emails

string[]

Verifizierte E-Mail-Adressen, die aus den genehmigten Sitzungen dieses Benutzers erfasst wurden, z. B. ["john@example.com"].

approved_phones

string[]

Verifizierte Telefonnummern, die aus den genehmigten Sitzungen dieses Benutzers erfasst wurden, z. B. ["+14155551234"].

features

object

Aggregierter Status pro Funktion über alle Sitzungen dieses Benutzers hinweg. Mögliche Schlüssel: ID_VERIFICATION, NFC, LIVENESS, FACE_MATCH, POA, QUESTIONNAIRE, EMAIL_VERIFICATION, PHONE, AML, IP_ANALYSIS, AGE_ESTIMATION, DATABASE_VALIDATION. Mögliche Werte: Approved, Declined, In Review, Not Finished, Resub Requested.

features_list

object[]

Dieselben Daten wie features, als geordnetes Array von {feature, status}-Objekten.

Show child attributes

last_session_at

string<date-time> | null

Zeitstempel der letzten Sitzung

first_session_at

string<date-time> | null

Zeitstempel der ersten Sitzung

last_activity_at

string<date-time> | null

Zeitstempel der letzten Aktivität bei diesem Benutzer (Sitzung, Transaktion, Statusänderung, Datenbearbeitung usw.).

​Überblick

​Wann Sie es verwenden

​Kontaktdaten

​Verifizierungslink senden

​Hinweise

​Berechtigungen

​Verwandte Seiten

Autorisierungen

Body

Antwort

Überblick

Wann Sie es verwenden

Kontaktdaten

Verifizierungslink senden

Hinweise

Berechtigungen

Verwandte Seiten