API para crear usuario: entidad de usuario del proveedor

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
}

Descripción general

Crea de forma explícita una entidad de usuario antes de que se ejecute cualquier sesión. La entidad devuelta queda en estado ACTIVE, salvo que indiques otra cosa. De forma opcional, la misma llamada envía a la persona un enlace de verificación por correo electrónico (consulta Enviar un enlace de verificación).

Cuándo usarlo

Precargar metadatos (nivel, origen del registro, etiquetas internas) antes de que el cliente se verifique.
Migrar desde otro proveedor: recrea en Didit tu lista de usuarios existente para que el historial y las analíticas partan de una base conocida.
Importar rostros de perfiles de confianza: crea primero el User y luego llama a Subir rostro de usuario con el didit_internal_id devuelto.
Casos de uso solo de transacciones: registra un User con vendor_data para poder enviar transacciones sin ejecutar nunca una sesión de Verificación de usuarios (KYC).
Invitar a alguien a verificarse: crea a la persona y envíale un enlace de verificación por correo electrónico en una sola llamada.

Datos de contacto

Puedes enviar los datos de contacto de la persona junto con los campos del perfil. first_name y last_name se unen con un espacio en full_name cuando no envías full_name. email y phone_number se guardan en metadata.contact, y country en metadata.address. country admite un código ISO 3166, alfa-2 o alfa-3 (ES o ESP), y se guarda en mayúsculas. Si el metadata que envías ya tiene un valor contact o address que no es un objeto JSON, Didit no lo sobrescribe: la solicitud responde con 400 en el campo de contacto correspondiente.

Enviar un enlace de verificación

Establece send_verification_link en true para invitar a la persona a verificarse en la misma solicitud. Didit crea una sesión de verificación para la persona en el flujo de verificación (workflow) indicado en workflow_id y le envía el enlace por correo electrónico a email. Usa language para elegir el idioma del correo; si lo omites, se envía en inglé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 y workflow_id son obligatorios al solicitar un enlace, y el flujo debe verificar a una persona: un flujo de Verificación de empresas (KYB) devuelve 400.
La sesión pasa por las mismas comprobaciones que Crear sesión. Un vendor_data en la lista de bloqueo o créditos insuficientes provocan una respuesta 400.
La persona y la sesión se crean juntas o no se crea ninguna. Cuando falla cualquier comprobación, no se guarda nada y no se envía ningún correo.
La respuesta incluye verification_link con el session_id, session_number, status, url y workflow_id de la sesión, y el email al que se envió. Sin enlace, verification_link es null.

Notas

vendor_data es obligatorio y debe ser único por aplicación. Intentar crear un duplicado devuelve un error de conflicto: usa PATCH /v3/users/{vendor_data}/ para actualizar un usuario existente.
vendor_data tiene un límite estricto de 2000 bytes (codificado en UTF-8). Un valor que supere ese límite devuelve un error de validación 400 en lugar de aceptarse.
Los campos que normalmente se derivan de sesiones verificadas (full_name, date_of_birth) pueden precargarse aquí, pero la primera sesión aprobada de Verificación de usuarios (KYC) puede sobrescribirlos.
Este endpoint no acepta imágenes faciales. Para asociar un rostro importado de confianza, usa POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ después de que este endpoint devuelva didit_internal_id.
La creación en sí no envía ningún webhook. Los cambios posteriores en el usuario envían user.data.updated o user.status.updated.
Con send_verification_link, la nueva sesión actualiza el usuario en la misma llamada, lo que envía user.data.updated.

Permisos

El secreto principal y las claves de API con acceso completo siempre pueden llamar a este endpoint. Una clave con acceso personalizado necesita permiso de escritura en Personas (users). Con send_verification_link: true también necesita permiso de escritura en Sesiones, porque la llamada crea una sesión y entrega su enlace. Sin él, la llamada responde 403 con This API key has no write access to sessions. y no se escribe nada. Una clave limitada a algunos flujos o a sesiones aprobadas no puede acceder a este endpoint. Los roles y permisos de la consola deciden qué puede hacer un miembro del equipo en la consola. No se evalúan en las solicitudes con clave de API.

Relacionado

Autorizaciones

x-api-key

string

header

requerido

La clave de API de tu aplicación, que encontrarás en Developers -> API keys en la Business Console. La clave principal tiene acceso completo. Una clave con nombre puede tener un alcance limitado: ninguno, lectura o escritura por recurso, limitada a algunos flujos o a sesiones aprobadas, a una lista de direcciones IP y a una fecha de caducidad. 401 significa que la clave es incorrecta, se revocó o expiró; 403 significa que no se envió ninguna clave, que la clave no tiene acceso a este recurso o acción, o que la solicitud provino de una dirección fuera de su lista de IP; 404 en una ruta de sesión significa que la sesión está fuera de los flujos o estados de la clave. Una clave sin acceso a contenido multimedia recibe las URL de imágenes, videos y PDF como null, y una clave sin permiso de escritura en sesiones recibe los enlaces y tokens de sesión como null. Consulta https://docs.didit.me/console/api-keys.

Cuerpo

application/json

vendor_data

string

requerido

Tu identificador único de este usuario (cadena de texto libre, NO un UUID). Debe ser único entre los usuarios de la aplicación; se compara exactamente tal como se envía.

full_name

string | null

Nombre legal completo del usuario.

Maximum string length: 512

display_name

string | null

Nombre visible descriptivo que se muestra en la consola (tiene prioridad sobre full_name en la interfaz).

Maximum string length: 255

date_of_birth

string<date> | null

Fecha de nacimiento en formato YYYY-MM-DD.

status

enum<string>

predeterminado:ACTIVE

Estado inicial del ciclo de vida. El valor predeterminado es ACTIVE.

Opciones disponibles:

ACTIVE,

FLAGGED,

BLOCKED

metadata

object | null

Objeto JSON arbitrario que adjuntas al usuario. Por defecto es {}.

approved_emails

string[]

Direcciones de correo electrónico de confianza previa para este usuario, por ejemplo ["john@example.com"].

approved_phones

string[]

Números de teléfono de confianza previa para este usuario, por ejemplo ["+14155551234"].

issuing_states

string[]

Países emisores registrados previamente (ISO 3166-1 alpha-3), por ejemplo ["USA"].

first_name

string

Nombre de pila. Cuando no se envía full_name, Didit une first_name y last_name con un espacio en full_name. No se devuelve como campo independiente.

Maximum string length: 255

last_name

string

Apellido. Se une con first_name para formar full_name cuando no se envía full_name. No se devuelve como campo independiente.

Maximum string length: 255

string<email>

Correo electrónico de contacto, que se guarda en metadata.contact.email (reemplaza cualquier email que envíes dentro de metadata.contact). Es obligatorio cuando send_verification_link es true: el enlace se envía a esta dirección. Si metadata.contact no es un objeto JSON, la llamada responde 400 en este campo.

phone_number

string

Número de teléfono de contacto, que se guarda en metadata.contact.phone_number. Si metadata.contact no es un objeto JSON, la llamada responde 400 en este campo.

Maximum string length: 32

country

string

País como código ISO 3166, alfa-2 o alfa-3 (ES o ESP). Se guarda en mayúsculas en metadata.address.country. Si metadata.address no es un objeto JSON, la llamada responde 400 en este campo.

Maximum string length: 3

send_verification_link

boolean

predeterminado:false

Si es true, Didit crea una sesión de verificación para la persona en workflow_id y le envía el enlace por correo electrónico a email. Requiere email y workflow_id. Una clave de API con alcance limitado también necesita permiso de escritura en sessions.

workflow_id

string<uuid>

El flujo de la sesión de verificación. Obligatorio cuando send_verification_link es true. Debe verificar a una persona: se rechaza un flujo de Verificación de empresas (KYB). En caso contrario, se ignora.

language

string

Idioma del correo electrónico de verificación, como código de idioma admitido. Inglés si se omite. Se ignora cuando send_verification_link no es true.

Maximum string length: 10

Respuesta

Usuario creado. El registro completo del usuario (con la misma estructura que Get User), más verification_link: la sesión de verificación que Didit envió por correo electrónico cuando send_verification_link era true; en caso contrario, null.

Detalle completo del usuario. Amplía UserListItem con metadatos, comentarios y updated_at.

verification_link

object | null

requerido

La sesión de verificación que Didit creó y envió por correo electrónico a la persona. Siempre presente: null cuando send_verification_link no era true.

Show child attributes

didit_internal_id

string<uuid>

UUID interno estable de Didit para este usuario.

vendor_data

string | null

Tu identificador único de este usuario (el que se envía al crear sesiones). Puede ser null si no se proporcionó ningún identificador propio.

display_name

string | null

Nombre visible personalizado que has definido

full_name

string | null

Nombre completo extraído de los documentos verificados

date_of_birth

string<date> | null

effective_name

string | null

Mejor nombre disponible: display_name si está definido; si no, full_name

status

enum<string>

Estado del ciclo de vida del registro del usuario (NO es un estado de sesión). ACTIVE es el valor predeterminado, FLAGGED marca al usuario para atención manual y BLOCKED impide nuevas sesiones para este vendor_data.

Opciones disponibles:

ACTIVE,

FLAGGED,

BLOCKED

portrait_image_url

string | null

URL prefirmada de la foto de retrato del usuario (caduca al cabo de unas horas)

session_count

integer

Número total de sesiones de verificación de este usuario

approved_count

integer

Número de sesiones aprobadas

declined_count

integer

Número de sesiones rechazadas

in_review_count

integer

Número de sesiones en revisión

issuing_states

string[]

Códigos ISO 3166-1 alpha-3 de los países emisores que figuran en los documentos de identidad aprobados de este usuario, p. ej., ["USA", "ESP"]. Array vacío si no hay ninguno.

approved_emails

string[]

Direcciones de correo electrónico verificadas obtenidas de las sesiones aprobadas de este usuario, p. ej., ["john@example.com"].

approved_phones

string[]

Números de teléfono verificados obtenidos de las sesiones aprobadas de este usuario, p. ej., ["+14155551234"].

features

object

Estado agregado por función de todas las sesiones de este usuario. Claves posibles: ID_VERIFICATION, NFC, LIVENESS, FACE_MATCH, POA, QUESTIONNAIRE, EMAIL_VERIFICATION, PHONE, AML, IP_ANALYSIS, AGE_ESTIMATION, DATABASE_VALIDATION. Valores posibles: Approved, Declined, In Review, Not Finished, Resub Requested.

features_list

object[]

Los mismos datos que features, como un array ordenado de objetos {feature, status}.

Show child attributes

last_session_at

string<date-time> | null

Marca de tiempo de la sesión más reciente

first_session_at

string<date-time> | null

Marca de tiempo de la primera sesión

last_activity_at

string<date-time> | null

Marca de tiempo de la actividad más reciente de este usuario (sesión, transacción, cambio de estado, edición de datos, etc.).

​Descripción general

​Cuándo usarlo

​Datos de contacto

​Enviar un enlace de verificación

​Notas

​Permisos

​Relacionado

Autorizaciones

Cuerpo

Respuesta

Descripción general

Cuándo usarlo

Datos de contacto

Enviar un enlace de verificación

Notas

Permisos

Relacionado