Crear usuari API: entitat d'usuari del proveïdor

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
}

Visió general

Crea explícitament una entitat d’usuari abans que s’executi cap sessió. L’entitat retornada queda en estat ACTIVE, tret que especifiquis una altra cosa. Opcionalment, la mateixa crida envia a la persona un enllaç de verificació (vegeu Envia un enllaç de verificació).

Quan utilitzar-lo

Precarregar metadades (nivell, origen de l’alta, etiquetes internes) abans que el client es verifiqui.
Migrar des d’un altre proveïdor: recrea el llistat d’usuaris actual a Didit perquè l’historial i les analítiques partin d’una base coneguda.
Importar rostres de perfil de confiança: crea primer l’usuari i després crida Puja el rostre de l’usuari amb el didit_internal_id retornat.
Casos només de transaccions: registra un usuari amb vendor_data perquè puguis enviar transaccions sense executar mai una sessió de Verificació d’usuaris (KYC).
Convidar algú a verificar-se: crea la persona i envia-li un enllaç de verificació en una sola crida.

Dades de contacte

Pots enviar les dades de contacte de la persona juntament amb els camps del perfil. first_name i last_name s’uneixen amb un espai a full_name quan no envies full_name. email i phone_number es guarden a metadata.contact, i country a metadata.address. country accepta un codi ISO 3166, alfa-2 o alfa-3 (ES o ESP), i es guarda en majúscules. Si les metadata que envies ja tenen un valor contact o address que no és un objecte JSON, Didit no el sobreescriu: la crida respon amb 400 al camp de contacte que ho necessitava.

Envia un enllaç de verificació

Estableix send_verification_link a true per convidar la persona a verificar-se en la mateixa crida. Didit crea una sessió de verificació per a la persona al flux de treball indicat a workflow_id i li envia l’enllaç a email. Fes servir language per triar l’idioma del correu; si no l’especifiques, serà l’anglès.

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 i workflow_id són obligatoris amb un enllaç, i el flux de treball ha de verificar una persona: un flux de treball de Verificació d’empreses (KYB) respon amb 400.
La sessió passa per les mateixes comprovacions que Crea una sessió. Un vendor_data que figuri a la llista de bloqueig o massa pocs crèdits responen amb 400.
La persona i la sessió es creen juntes o no se’n crea cap. Si falla qualsevol comprovació, no s’escriu res i no s’envia cap correu.
La resposta inclou verification_link amb el session_id, session_number, status, url i workflow_id de la sessió, i el email al qual s’ha enviat. Sense enllaç, verification_link és null.

Notes

vendor_data és obligatori i ha de ser únic per aplicació. Si intentes crear un duplicat, es retorna un error de conflicte; fes servir PATCH /v3/users/{vendor_data}/ per actualitzar un usuari existent.
vendor_data té un límit estricte de 2000 bytes (codificat en UTF-8). Un valor que superi aquest límit retorna un error de validació 400 en lloc de ser acceptat.
Els camps que normalment es deriven de sessions verificades (full_name, date_of_birth) es poden precarregar aquí, però la primera sessió de Verificació d’usuaris (KYC) aprovada els pot sobreescriure.
Aquest endpoint no accepta imatges de rostres. Per adjuntar un rostre importat de confiança, fes servir POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ després que aquest endpoint retorni didit_internal_id.
La creació en si no envia cap webhook. Els canvis posteriors a l’usuari envien user.data.updated o user.status.updated.
Amb send_verification_link, la nova sessió actualitza l’usuari en la mateixa crida, cosa que envia user.data.updated.

Permisos

El secret principal i les claus d’API amb accés complet sempre poden cridar aquest endpoint. Una clau amb accés personalitzat necessita permís d’escriptura de Persones (users). Amb send_verification_link: true també necessita permís d’escriptura de Sessions, perquè la crida crea una sessió i en lliura l’enllaç. Sense aquest permís, la crida respon amb 403 i el missatge This API key has no write access to sessions., i no s’escriu res. Una clau limitada a alguns fluxos de treball o a sessions aprovades no pot accedir a aquest endpoint. Els rols i permisos de la Consola determinen què pot fer un membre de l’equip a la Consola. No s’avaluen per a les sol·licituds amb clau d’API.

Relacionat

Autoritzacions

x-api-key

string

header

requerit

La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys.

Cos

application/json

vendor_data

string

requerit

El teu identificador únic per a aquest usuari (cadena de text lliure, NO un UUID). Ha de ser únic entre els usuaris de l'aplicació; coincideix exactament amb el valor enviat.

full_name

string | null

Nom legal complet de l'usuari.

Maximum string length: 512

display_name

string | null

Nom descriptiu que es mostra a la consola (té prioritat sobre full_name per a la visualització a la interfície d'usuari).

Maximum string length: 255

date_of_birth

string<date> | null

Data de naixement en format YYYY-MM-DD.

status

enum<string>

predeterminat:ACTIVE

Estat inicial del cicle de vida. Per defecte és ACTIVE.

Opcions disponibles:

ACTIVE,

FLAGGED,

BLOCKED

metadata

object | null

Objecte JSON arbitrari que adjuntes a l'usuari. Per defecte és {}.

approved_emails

string[]

Adreces de correu electrònic de confiança prèvia per a aquest usuari, p. ex. ["john@example.com"].

approved_phones

string[]

Números de telèfon de confiança prèvia per a aquest usuari, p. ex. ["+14155551234"].

issuing_states

string[]

Països emissors preenregistrats (ISO 3166-1 alfa-3), p. ex. ["USA"].

first_name

string

Nom de pila. Quan no s'envia full_name, Didit uneix first_name i last_name amb un espai per formar full_name. No es retorna com a camp separat.

Maximum string length: 255

last_name

string

Cognom. S'uneix amb first_name per formar full_name quan no s'envia full_name. No es retorna com a camp separat.

Maximum string length: 255

string<email>

Correu electrònic de contacte, emmagatzemat a metadata.contact.email (substitueix un email que enviïs dins de metadata.contact). Obligatori quan send_verification_link és true: l'enllaç s'envia a aquesta adreça. Si metadata.contact no és un objecte JSON, la crida respon 400 en aquest camp.

phone_number

string

Número de telèfon de contacte, emmagatzemat a metadata.contact.phone_number. Si metadata.contact no és un objecte JSON, la crida respon 400 en aquest camp.

Maximum string length: 32

country

string

País com a codi ISO 3166, alpha-2 o alpha-3 (ES o ESP). S'emmagatzema en majúscules a metadata.address.country. Si metadata.address no és un objecte JSON, la crida retorna 400 per a aquest camp.

Maximum string length: 3

send_verification_link

boolean

predeterminat:false

Quan és true, Didit crea una sessió de verificació per a la persona a workflow_id i li envia l'enllaç per correu electrònic a email. Requereix email i workflow_id. Una clau d'API amb abast també necessita escriptura a sessions.

workflow_id

string<uuid>

El flux de treball de la sessió de verificació. Obligatori quan send_verification_link és true. Ha de verificar una persona: es rebutja un flux de treball de Verificació d'empreses (KYB). S'ignora en cas contrari.

language

string

Idioma del correu electrònic de verificació, com a codi d'idioma admès. Anglès si s'omet. S'ignora quan send_verification_link no és true.

Maximum string length: 10

Resposta

Usuari creat. El registre complet de l'usuari (mateixa estructura que a Get User), més verification_link: la sessió de verificació que Didit ha enviat per correu electrònic quan send_verification_link era true; altrament, null.

Detall complet de l'usuari. Amplia UserListItem amb metadades, comentaris i updated_at.

verification_link

object | null

requerit

La sessió de verificació que Didit ha creat i ha enviat per correu electrònic a la persona. Sempre present: null quan send_verification_link no era true.

Show child attributes

didit_internal_id

string<uuid>

UUID intern estable de Didit per a aquest usuari.

vendor_data

string | null

El teu identificador únic per a aquest usuari (passat en crear sessions). Pot ser nul quan no s'ha proporcionat cap identificador de proveïdor.

display_name

string | null

Nom visible personalitzat definit per tu

full_name

string | null

Nom complet extret dels documents verificats

date_of_birth

string<date> | null

effective_name

string | null

Millor nom disponible: display_name si està definit, en cas contrari full_name

status

enum<string>

Estat del cicle de vida del registre d'usuari (NO és un estat de la sessió). ACTIVE és el valor per defecte, FLAGGED marca l'usuari per a atenció manual, BLOCKED impedeix noves sessions per a aquest vendor_data.

Opcions disponibles:

ACTIVE,

FLAGGED,

BLOCKED

portrait_image_url

string | null

URL presignada de la foto de retrat de l'usuari (caduca al cap d'unes hores)

session_count

integer

Nombre total de sessions de verificació per a aquest usuari

approved_count

integer

Nombre de sessions aprovades

declined_count

integer

Nombre de sessions rebutjades

in_review_count

integer

Nombre de sessions en revisió

issuing_states

string[]

Codis ISO 3166-1 alpha-3 dels països emissors que consten als documents d'identitat aprovats d'aquest usuari, p. ex. ["USA", "ESP"]. Matriu buida si no n'hi ha cap.

approved_emails

string[]

Adreces de correu electrònic verificades recollides de les sessions aprovades d'aquest usuari, p. ex. ["john@example.com"].

approved_phones

string[]

Números de telèfon verificats recollits de les sessions aprovades d'aquest usuari, p. ex. ["+14155551234"].

features

object

Estat agregat per funcionalitat a totes les sessions d'aquest usuari. Claus possibles: ID_VERIFICATION, NFC, LIVENESS, FACE_MATCH, POA, QUESTIONNAIRE, EMAIL_VERIFICATION, PHONE, AML, IP_ANALYSIS, AGE_ESTIMATION, DATABASE_VALIDATION. Valors possibles: Approved, Declined, In Review, Not Finished, Resub Requested.

features_list

object[]

Les mateixes dades que features, com una llista ordenada d'objectes {feature, status}.

Show child attributes

last_session_at

string<date-time> | null

Marca de temps de la sessió més recent

first_session_at

string<date-time> | null

Marca de temps de la primera sessió

last_activity_at

string<date-time> | null

Marca de temps de l'activitat més recent d'aquest usuari (sessió, transacció, canvi d'estat, edició de dades, etc.).

​Visió general

​Quan utilitzar-lo

​Dades de contacte

​Envia un enllaç de verificació

​Notes

​Permisos

​Relacionat

Autoritzacions

Cos

Resposta

Visió general

Quan utilitzar-lo

Dades de contacte

Envia un enllaç de verificació

Notes

Permisos

Relacionat