API per creare utenti: entità User del vendor

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
}

Panoramica

Crea esplicitamente un’entità utente prima che venga eseguita qualsiasi sessione. L’entità restituita entra nello stato ACTIVE, a meno che tu non specifichi diversamente. Facoltativamente, la stessa chiamata invia alla persona via email un link di verifica (vedi Invia un link di verifica).

Quando usarlo

Precaricare i metadati (livello, origine della registrazione, tag interni) prima che il cliente esegua la verifica.
Migrare da un altro fornitore: ricreare l’elenco degli utenti esistenti in Didit, così che cronologia e analisi partano da una base nota.
Importare volti di profili attendibili: crea prima lo User, poi chiama Carica il volto dell’utente con il didit_internal_id restituito.
Casi d’uso basati solo sulle transazioni: registra un utente con vendor_data in modo da poter inviare transazioni senza mai eseguire una sessione di Verifica degli utenti (KYC).
Invitare qualcuno a verificarsi: crea la persona e inviale via email un link di verifica in un’unica chiamata.

Dati di contatto

Puoi inviare i dati di contatto della persona insieme ai campi del profilo. Se non invii full_name, first_name e last_name vengono uniti con uno spazio in full_name. email e phone_number vengono salvati in metadata.contact, e country in metadata.address. country accetta un codice ISO 3166, alpha-2 o alpha-3 (ES o ESP), e viene salvato in maiuscolo. Se il metadata che invii contiene già un valore contact o address che non è un oggetto JSON, Didit non lo sovrascrive: la chiamata risponde con 400 sul campo di contatto che ne aveva bisogno.

Invia un link di verifica

Imposta send_verification_link su true per invitare la persona a verificarsi nella stessa chiamata. Didit crea per la persona una sessione di verifica sul workflow indicato in workflow_id e le invia via email il link all’indirizzo email. Usa language per scegliere la lingua dell’email; se lo ometti, l’email è in inglese.

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 e workflow_id sono obbligatori quando si invia un link, e il workflow deve verificare una persona: un workflow di Verifica aziendale (KYB) risponde con 400.
La sessione è sottoposta agli stessi controlli di Crea sessione. La presenza di un vendor_data nella blocklist o l’insufficienza di crediti restituiscono 400.
La persona e la sessione vengono create insieme oppure non viene creato nulla. Quando un controllo fallisce, non viene scritto nulla e non viene inviata alcuna email.
La risposta contiene verification_link con session_id, session_number, status, url, workflow_id della sessione e l’email a cui è stato inviato. Senza link, verification_link è null.

Note

vendor_data è obbligatorio e deve essere univoco per applicazione. Tentare di creare un duplicato restituisce un errore di conflitto: usa PATCH /v3/users/{vendor_data}/ per aggiornare un utente esistente.
vendor_data ha un limite rigido di 2000 byte (codificati in UTF-8). Un valore che supera tale limite restituisce un errore di validazione 400 invece di essere accettato.
I campi che normalmente derivano dalle sessioni verificate (full_name, date_of_birth) possono essere precompilati qui, ma possono essere sovrascritti dalla prima sessione di Verifica degli utenti (KYC) approvata.
Questo endpoint non accetta immagini del volto. Per associare un volto importato attendibile, usa POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ dopo che questo endpoint ha restituito didit_internal_id.
La creazione in sé non invia alcun webhook. Le modifiche successive all’utente inviano user.data.updated o user.status.updated.
Con send_verification_link, la nuova sessione aggiorna l’utente nella stessa chiamata, che invia user.data.updated.

Autorizzazioni

Il segreto primario e le chiavi API con accesso completo possono sempre chiamare questo endpoint. Una chiave con accesso personalizzato richiede l’autorizzazione di scrittura per Persone (users). Con send_verification_link: true richiede anche l’autorizzazione di scrittura per Sessioni, perché la chiamata crea una sessione e ne fornisce il link. Senza di essa, la chiamata risponde con 403 con This API key has no write access to sessions. e non viene scritto nulla. Una chiave limitata ad alcuni workflow o alle sessioni approvate non può raggiungere questo endpoint. I ruoli e le autorizzazioni della Console determinano cosa può fare un membro del team nella Console. Non vengono valutati per le richieste con chiave API.

Correlati

Autorizzazioni

x-api-key

string

header

obbligatorio

La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys.

Corpo

application/json

vendor_data

string

obbligatorio

Il tuo identificatore univoco per questo utente (stringa a formato libero, NON un UUID). Deve essere univoco tra gli utenti dell'applicazione; confrontato esattamente come inviato.

full_name

string | null

Nome legale completo dell'utente.

Maximum string length: 512

display_name

string | null

Nome descrittivo mostrato nella console (ha la precedenza su full_name per la visualizzazione dell'interfaccia utente).

Maximum string length: 255

date_of_birth

string<date> | null

Data di nascita nel formato YYYY-MM-DD.

status

enum<string>

predefinito:ACTIVE

Stato iniziale del ciclo di vita. Il valore predefinito è ACTIVE.

Opzioni disponibili:

ACTIVE,

FLAGGED,

BLOCKED

metadata

object | null

Oggetto JSON arbitrario da allegare all'utente. Il valore predefinito è {}.

approved_emails

string[]

Indirizzi email già considerati attendibili per questo utente, ad es. ["john@example.com"].

approved_phones

string[]

Numeri di telefono già considerati attendibili per questo utente, ad es. ["+14155551234"].

issuing_states

string[]

Paesi di emissione preregistrati (ISO 3166-1 alpha-3), ad es. ["USA"].

first_name

string

Nome. Quando full_name non viene inviato, Didit unisce first_name e last_name con uno spazio in full_name. Non restituito come campo separato.

Maximum string length: 255

last_name

string

Cognome. Unito a first_name in full_name quando full_name non viene inviato. Non restituito come campo separato.

Maximum string length: 255

string<email>

Email di contatto, memorizzata in metadata.contact.email (sostituisce l'email inviata all'interno di metadata.contact). Obbligatoria quando send_verification_link è true: il link viene inviato a questo indirizzo. Se metadata.contact non è un oggetto JSON, la chiamata risponde 400 su questo campo.

phone_number

string

Numero di telefono di contatto, memorizzato in metadata.contact.phone_number. Se metadata.contact non è un oggetto JSON, la chiamata risponde 400 su questo campo.

Maximum string length: 32

country

string

Paese come codice ISO 3166, alpha-2 o alpha-3 (ES o ESP). Memorizzato in lettere maiuscole in metadata.address.country. Se metadata.address non è un oggetto JSON, la chiamata risponde 400 su questo campo.

Maximum string length: 3

send_verification_link

boolean

predefinito:false

Quando è true, Didit crea una sessione di verifica per la persona su workflow_id e le invia via email il link all'indirizzo email. Richiede email e workflow_id. Una chiave API con ambito limitato richiede anche l'autorizzazione di scrittura per sessions.

workflow_id

string<uuid>

Il workflow della sessione di verifica. Obbligatorio quando send_verification_link è true. Deve verificare una persona fisica: un workflow di Verifica aziendale (KYB) viene rifiutato. Ignorato altrimenti.

language

string

Lingua dell'email di verifica, come codice di una lingua supportata. Inglese se omessa. Ignorata quando send_verification_link non è true.

Maximum string length: 10

Risposta

Utente creato. Il record utente completo (stessa struttura di Get User), più verification_link: la sessione di verifica inviata via email da Didit quando send_verification_link era true, altrimenti null.

Dettaglio completo dell'utente. Estende UserListItem con metadati, commenti e updated_at.

verification_link

object | null

obbligatorio

La sessione di verifica creata e inviata via email da Didit alla persona. Sempre presente: null quando send_verification_link non era true.

Show child attributes

didit_internal_id

string<uuid>

UUID interno stabile di Didit per questo utente.

vendor_data

string | null

Il tuo identificatore univoco per questo utente (passato durante la creazione delle sessioni). Può essere null se non è stato fornito alcun identificatore del fornitore.

display_name

string | null

Nome visualizzato personalizzato impostato da te

full_name

string | null

Nome completo estratto dai documenti verificati

date_of_birth

string<date> | null

effective_name

string | null

Miglior nome disponibile: display_name se impostato, altrimenti full_name

status

enum<string>

Stato del ciclo di vita del record utente (NON uno stato della sessione). ACTIVE è il valore predefinito, FLAGGED contrassegna l'utente per una verifica manuale, BLOCKED impedisce nuove sessioni per questo vendor_data.

Opzioni disponibili:

ACTIVE,

FLAGGED,

BLOCKED

portrait_image_url

string | null

URL prefirmato della foto ritratto dell'utente (scade dopo alcune ore)

session_count

integer

Numero totale di sessioni di verifica per questo utente

approved_count

integer

Numero di sessioni approvate

declined_count

integer

Numero di sessioni rifiutate

in_review_count

integer

Numero di sessioni in revisione

issuing_states

string[]

Codici ISO 3166-1 alpha-3 dei paesi di emissione rilevati nei documenti d'identità approvati di questo utente, ad es. ["USA", "ESP"]. Array vuoto se assenti.

approved_emails

string[]

Indirizzi email verificati raccolti dalle sessioni approvate di questo utente, ad es. ["john@example.com"].

approved_phones

string[]

Numeri di telefono verificati raccolti dalle sessioni approvate di questo utente, ad es. ["+14155551234"].

features

object

Stato aggregato per funzionalità in tutte le sessioni di questo utente. Chiavi possibili: ID_VERIFICATION, NFC, LIVENESS, FACE_MATCH, POA, QUESTIONNAIRE, EMAIL_VERIFICATION, PHONE, AML, IP_ANALYSIS, AGE_ESTIMATION, DATABASE_VALIDATION. Valori possibili: Approved, Declined, In Review, Not Finished, Resub Requested.

features_list

object[]

Gli stessi dati di features, sotto forma di array ordinato di oggetti {feature, status}.

Show child attributes

last_session_at

string<date-time> | null

Timestamp della sessione più recente

first_session_at

string<date-time> | null

Timestamp della prima sessione

last_activity_at

string<date-time> | null

Timestamp dell'attività più recente su questo utente (sessione, transazione, cambio di stato, modifica dei dati, ecc.).

​Panoramica

​Quando usarlo

​Dati di contatto

​Invia un link di verifica

​Note

​Autorizzazioni

​Correlati

Autorizzazioni

Corpo

Risposta

Panoramica

Quando usarlo

Dati di contatto

Invia un link di verifica

Note

Autorizzazioni

Correlati