API para criar usuário: entidade User do fornecedor

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
}

Visão geral

Cria explicitamente uma entidade de usuário antes de qualquer sessão ser executada. A entidade retornada fica com o status ACTIVE, a menos que você especifique outro. Opcionalmente, a mesma chamada envia à pessoa, por e-mail, um link de verificação (consulte Enviar um link de verificação).

Quando usar

Pré-carregar metadados (nível, origem do cadastro, tags internas) antes de o cliente se verificar.
Migrar de outro fornecedor: recrie sua base de usuários existente na Didit para que o histórico e as análises partam de uma base conhecida.
Importar rostos de perfil confiáveis: crie primeiro o usuário e depois chame Enviar rosto do usuário com o didit_internal_id retornado.
Casos de uso apenas com transações: registre um usuário com vendor_data para enviar transações sem nunca executar uma sessão de Verificação de Usuário (KYC).
Convidar alguém para realizar a verificação: crie a pessoa e envie a ela um link de verificação por e-mail em uma única chamada.

Dados de contato

Você pode enviar os dados de contato da pessoa junto com os campos do perfil. first_name e last_name são unidos com um espaço em full_name quando você não envia full_name. email e phone_number são armazenados em metadata.contact, e country em metadata.address. country aceita um código ISO 3166, alfa-2 ou alfa-3 (ES ou ESP), e é armazenado em maiúsculas. Se o metadata que você enviar já tiver um valor para contact ou address que não seja um objeto JSON, a Didit não o sobrescreve: a chamada retorna 400 para o campo de contato que precisava dele.

Enviar um link de verificação

Defina send_verification_link como true para convidar a pessoa a realizar a verificação na mesma requisição. A Didit cria uma sessão de verificação para a pessoa no fluxo de verificação (workflow) indicado em workflow_id e envia o link por e-mail para email. Use language para escolher o idioma do e-mail; se você o omitir, o e-mail será em 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 e workflow_id são obrigatórios ao enviar um link, e o fluxo precisa verificar uma pessoa: um fluxo de Verificação de empresas (KYB) retorna 400.
A sessão passa pelas mesmas verificações de Criar sessão. Um vendor_data na lista de bloqueio ou créditos insuficientes resultam em 400.
A pessoa e a sessão são criadas juntas ou não são criadas. Quando qualquer verificação falha, nada é gravado e nenhum e-mail é enviado.
A resposta traz verification_link com session_id, session_number, status, url e workflow_id da sessão, além do email para o qual o link foi enviado. Sem link, verification_link é null.

Observações

vendor_data é obrigatório e deve ser único por aplicação. Tentar criar um duplicado retorna um erro de conflito: use PATCH /v3/users/{vendor_data}/ para atualizar um usuário existente.
vendor_data tem um limite rígido de 2000 bytes (codificado em UTF-8). Um valor acima desse limite retorna um erro de validação 400 em vez de ser aceito.
Campos que normalmente são derivados de sessões verificadas (full_name, date_of_birth) podem ser preenchidos previamente aqui, mas podem ser sobrescritos pela primeira sessão de Verificação de usuário (KYC) aprovada.
Este endpoint não aceita imagens de rosto. Para anexar um rosto importado confiável, use POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ depois que este endpoint retornar didit_internal_id.
A criação em si não envia nenhum webhook. Alterações posteriores no usuário enviam user.data.updated ou user.status.updated.
Com send_verification_link, a nova sessão atualiza o usuário na mesma requisição, o que envia user.data.updated.

Permissões

O segredo principal e as chaves de API com acesso total sempre podem chamar este endpoint. Uma chave com acesso personalizado precisa de permissão de escrita em Pessoas (users). Com send_verification_link: true, ela também precisa de permissão de escrita em Sessões, porque a chamada cria uma sessão e entrega o link dela. Sem essa permissão, a chamada responde 403 com This API key has no write access to sessions. e nada é gravado. Uma chave limitada a alguns fluxos ou a sessões aprovadas não consegue acessar este endpoint. As funções e permissões do Console definem o que um membro da equipe pode fazer no Console. Elas não são avaliadas em requisições feitas com chave de API.

Relacionados

Autorizações

x-api-key

string

header

obrigatório

Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está errada, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys.

Corpo

application/json

vendor_data

string

obrigatório

Seu identificador exclusivo deste usuário (string livre, NÃO um UUID). Deve ser único entre os usuários da aplicação; comparado exatamente como enviado.

full_name

string | null

Nome legal completo do usuário.

Maximum string length: 512

display_name

string | null

Nome de exibição amigável mostrado no console (tem prioridade sobre full_name na exibição da interface).

Maximum string length: 255

date_of_birth

string<date> | null

Data de nascimento no formato YYYY-MM-DD.

status

enum<string>

padrão:ACTIVE

Status inicial do ciclo de vida. O padrão é ACTIVE.

Opções disponíveis:

ACTIVE,

FLAGGED,

BLOCKED

metadata

object | null

Objeto JSON arbitrário que você anexa ao usuário. O padrão é {}.

approved_emails

string[]

Endereços de e-mail pré-confiáveis deste usuário, por exemplo ["john@example.com"].

approved_phones

string[]

Números de telefone pré-confiáveis deste usuário, por exemplo ["+14155551234"].

issuing_states

string[]

Países emissores pré-registrados (ISO 3166-1 alpha-3), por exemplo ["USA"].

first_name

string

Nome próprio. Quando full_name não é enviado, a Didit junta first_name e last_name com um espaço em full_name. Não é retornado como um campo separado.

Maximum string length: 255

last_name

string

Sobrenome. Combinado com first_name em full_name quando full_name não é enviado. Não é retornado como campo separado.

Maximum string length: 255

string<email>

E-mail de contato, armazenado em metadata.contact.email (substitui um email que você envie dentro de metadata.contact). Obrigatório quando send_verification_link é true: o link é enviado para este endereço. Se metadata.contact não for um objeto JSON, a chamada responde 400 neste campo.

phone_number

string

Número de telefone de contato, armazenado em metadata.contact.phone_number. Se metadata.contact não for um objeto JSON, a chamada responde 400 neste campo.

Maximum string length: 32

country

string

País como código ISO 3166, alpha-2 ou alpha-3 (ES ou ESP). Armazenado em maiúsculas em metadata.address.country. Se metadata.address não for um objeto JSON, a chamada responde 400 neste campo.

Maximum string length: 3

send_verification_link

boolean

padrão:false

Quando true, a Didit cria uma sessão de verificação para a pessoa no workflow_id e envia o link por e-mail para email. Exige email e workflow_id. Uma chave de API com escopo também precisa de permissão de escrita em sessions.

workflow_id

string<uuid>

O fluxo da sessão de verificação. Obrigatório quando send_verification_link é true. Ele deve verificar uma pessoa: um fluxo de Verificação de empresas (KYB) é recusado. Ignorado caso contrário.

language

string

Idioma do e-mail de verificação, como um código de idioma suportado. Inglês quando omitido. Ignorado quando send_verification_link não é true.

Maximum string length: 10

Resposta

Usuário criado. O registro completo do usuário (mesmo formato de Get User), mais verification_link: a sessão de verificação que a Didit enviou por e-mail quando send_verification_link era true; caso contrário, null.

Detalhes completos do usuário. Estende UserListItem com metadados, comentários e updated_at.

verification_link

object | null

obrigatório

A sessão de verificação que a Didit criou e enviou por e-mail à pessoa. Sempre presente: null quando send_verification_link não era true.

Show child attributes

didit_internal_id

string<uuid>

UUID interno estável da Didit para este usuário.

vendor_data

string | null

Seu identificador exclusivo deste usuário (passado ao criar sessões). Pode ser nulo quando nenhum identificador do fornecedor foi informado.

display_name

string | null

Nome de exibição personalizado definido por você

full_name

string | null

Nome completo extraído dos documentos verificados

date_of_birth

string<date> | null

effective_name

string | null

Melhor nome disponível: display_name, se definido; caso contrário, full_name

status

enum<string>

Status do ciclo de vida do registro do usuário (NÃO é um status de sessão). ACTIVE é o padrão, FLAGGED marca o usuário para atenção manual e BLOCKED impede novas sessões para este vendor_data.

Opções disponíveis:

ACTIVE,

FLAGGED,

BLOCKED

portrait_image_url

string | null

URL pré-assinada da foto de retrato do usuário (expira após algumas horas)

session_count

integer

Número total de sessões de verificação deste usuário

approved_count

integer

Número de sessões aprovadas

declined_count

integer

Número de sessões recusadas

in_review_count

integer

Número de sessões em revisão

issuing_states

string[]

Códigos ISO 3166-1 alpha-3 dos países emissores encontrados nos documentos de identidade aprovados deste usuário, por exemplo, ["USA", "ESP"]. Array vazio quando não houver nenhum.

approved_emails

string[]

Endereços de e-mail verificados coletados das sessões aprovadas deste usuário, por exemplo, ["john@example.com"].

approved_phones

string[]

Números de telefone verificados coletados das sessões aprovadas deste usuário, por exemplo, ["+14155551234"].

features

object

Status agregado por recurso em todas as sessões deste usuário. Chaves possíveis: ID_VERIFICATION, NFC, LIVENESS, FACE_MATCH, POA, QUESTIONNAIRE, EMAIL_VERIFICATION, PHONE, AML, IP_ANALYSIS, AGE_ESTIMATION, DATABASE_VALIDATION. Valores possíveis: Approved, Declined, In Review, Not Finished, Resub Requested.

features_list

object[]

Os mesmos dados de features, como um array ordenado de objetos {feature, status}.

Show child attributes

last_session_at

string<date-time> | null

Data e hora da sessão mais recente

first_session_at

string<date-time> | null

Data e hora da primeira sessão

last_activity_at

string<date-time> | null

Data e hora da atividade mais recente deste usuário (sessão, transação, mudança de status, edição de dados etc.).

​Visão geral

​Quando usar

​Dados de contato

​Enviar um link de verificação

​Observações

​Permissões

​Relacionados

Autorizações

Corpo

Resposta

Visão geral

Quando usar

Dados de contato

Enviar um link de verificação

Observações

Permissões

Relacionados