Criar utilizador API: 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 utilizador antes de ser executada qualquer sessão. A entidade devolvida fica no estado ACTIVE, salvo indicação em contrário. Opcionalmente, a mesma chamada envia à pessoa por e-mail uma ligação de verificação (ver Enviar uma ligação de verificação).

Quando usar

Pré-preencher metadados (nível, origem do registo, etiquetas internas) antes de o cliente se verificar.
Migrar de outro fornecedor: recriar a lista de utilizadores existente na Didit para que o histórico e as análises partam de uma base conhecida.
Importar rostos de perfil fidedignos: criar primeiro o utilizador e, depois, chamar Carregar rosto do utilizador com o didit_internal_id devolvido.
Casos de utilização apenas de transações: registar um utilizador com vendor_data para poder submeter transações sem executar nunca uma sessão de Verificação de utilizadores (KYC).
Convidar alguém a verificar-se: criar a pessoa e enviar-lhe por e-mail uma ligação de verificação numa só chamada.

Dados de contacto

Pode enviar os dados de contacto da pessoa juntamente com os campos do perfil. first_name e last_name são unidos por um espaço em full_name quando não envia full_name. email e phone_number são guardados em metadata.contact, e country em metadata.address. country aceita um código ISO 3166, de duas ou três letras (ES ou ESP), e é guardado em maiúsculas. Se o metadata enviado já tiver um valor contact ou address que não seja um objeto JSON, a Didit não o substitui: a chamada responde com 400 no campo que dele necessitava.

Enviar uma ligação de verificação

Defina send_verification_link como true para convidar a pessoa a verificar-se na mesma chamada. A Didit cria uma sessão de verificação para a pessoa no fluxo indicado em workflow_id e envia a ligação para o endereço de e-mail especificado em email. Use language para escolher o idioma do e-mail; se o omitir, o e-mail fica 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 com uma ligação, e o fluxo tem de verificar uma pessoa: um fluxo de Verificação de empresas (KYB) responde com 400.
A sessão passa pelas mesmas validações que Criar sessão. Um vendor_data que esteja na lista de bloqueio ou créditos insuficientes responde com 400.
A pessoa e a sessão são criadas em conjunto ou não são criadas. Quando alguma validação falha, nada é gravado e não é enviado nenhum e-mail.
A resposta inclui verification_link com o session_id, o session_number, o status, o url, o workflow_id e o email para onde foi enviada. Sem ligação, verification_link é null.

Notas

vendor_data é obrigatório e tem de ser único por aplicação. Tentar criar um duplicado devolve um erro de conflito. Para atualizar um utilizador existente, use PATCH /v3/users/{vendor_data}/.
vendor_data tem um limite rígido de 2000 bytes (codificado em UTF-8). Um valor acima desse limite devolve um erro de validação 400 em vez de ser aceite.
Os campos normalmente derivados de sessões verificadas (full_name, date_of_birth) podem ser pré-preenchidos aqui, mas podem ser substituídos pela primeira sessão de Verificação de utilizadores (KYC) aprovada.
Este endpoint não aceita imagens de rosto. Para associar um rosto importado fidedigno, use POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ depois de este endpoint devolver o didit_internal_id.
A própria criação não envia nenhum webhook. As alterações posteriores ao utilizador enviam user.data.updated ou user.status.updated.
Com send_verification_link, a nova sessão atualiza o utilizador na mesma chamada, o que envia user.data.updated.

Permissões

O segredo primário e as chaves de API com acesso total podem sempre chamar este endpoint. Uma chave com acesso personalizado precisa de permissão de escrita em Pessoas (users). Com send_verification_link: true, precisa também de permissão de escrita em Sessões, porque a chamada cria uma sessão e entrega a respetiva ligação. Sem essa permissão, a chamada responde com 403 e a mensagem 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 aceder a este endpoint. As funções e permissões da Consola determinam o que um membro da equipa pode fazer na Consola. Não são avaliadas para pedidos feitos com chaves de API.

Relacionados

Autorizações

x-api-key

string

header

obrigatório

A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, 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á incorreta, 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 o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys.

Corpo

application/json

vendor_data

string

obrigatório

O seu identificador exclusivo para este utilizador (string de formato livre, NÃO um UUID). Deve ser exclusivo entre os utilizadores da aplicação; correspondido exatamente como enviado.

full_name

string | null

Nome completo legal do utilizador.

Maximum string length: 512

display_name

string | null

Nome de apresentação amigável apresentado na consola (tem precedência sobre full_name para exibição na IU).

Maximum string length: 255

date_of_birth

string<date> | null

Data de nascimento no formato YYYY-MM-DD.

status

enum<string>

padrão:ACTIVE

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

Opções disponíveis:

ACTIVE,

FLAGGED,

BLOCKED

metadata

object | null

Objeto JSON arbitrário que anexa ao utilizador. O valor predefinido é {}.

approved_emails

string[]

Endereços de e-mail previamente considerados fiáveis para este utilizador, por exemplo ["john@example.com"].

approved_phones

string[]

Números de telefone previamente considerados fiáveis para este utilizador, por exemplo ["+14155551234"].

issuing_states

string[]

Países emissores pré-registados (ISO 3166-1 alfa-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 é devolvido como um campo separado.

Maximum string length: 255

last_name

string

Apelido. Juntado a first_name em full_name quando full_name não é enviado. Não é devolvido como um campo separado.

Maximum string length: 255

string<email>

E-mail de contacto, armazenado em metadata.contact.email (substitui um email enviado dentro de metadata.contact). Obrigatório quando send_verification_link for true: a ligação é enviada 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 contacto, guardado em metadata.contact.phone_number. Se metadata.contact não for um objeto JSON, a chamada responde com 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 devolve 400 para este 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 em workflow_id e envia-lhe a ligação por e-mail para email. Requer email e workflow_id. Uma chave de API com âmbito também necessita 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 for true. Tem de verificar uma pessoa: um fluxo de Verificação de empresas (KYB) é recusado. Caso contrário, é ignorado.

language

string

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

Maximum string length: 10

Resposta

Utilizador criado. O registo completo do utilizador (mesma estrutura que Obter utilizador), 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.

Detalhe completo do utilizador. 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 se send_verification_link não foi true.

Show child attributes

didit_internal_id

string<uuid>

UUID interno estável da Didit para este utilizador.

vendor_data

string | null

O seu identificador exclusivo para este utilizador (transmitido ao criar sessões). Pode ser nulo quando não tiver sido fornecido nenhum identificador de fornecedor.

display_name

string | null

Nome de apresentação personalizado definido por si

full_name

string | null

Nome completo extraído de 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>

Estado do ciclo de vida do registo do utilizador (NÃO é um estado da sessão). ACTIVE é o padrão, FLAGGED marca o utilizador para atenção manual, BLOCKED impede novas sessões para este vendor_data.

Opções disponíveis:

ACTIVE,

FLAGGED,

BLOCKED

portrait_image_url

string | null

URL pré-assinado da fotografia de retrato do utilizador (expira após algumas horas)

session_count

integer

Número total de sessões de verificação para este utilizador

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 análise

issuing_states

string[]

Códigos ISO 3166-1 alfa-3 dos países emissores observados nos documentos de identificação aprovados deste utilizador, por exemplo, ["USA", "ESP"]. Array vazio quando não houver nenhum.

approved_emails

string[]

Endereços de e-mail verificados recolhidos a partir das sessões aprovadas deste utilizador, por exemplo, ["john@example.com"].

approved_phones

string[]

Números de telefone verificados recolhidos a partir das sessões aprovadas deste utilizador, por exemplo, ["+14155551234"].

features

object

Estado agregado por funcionalidade em todas as sessões deste utilizador. 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 que features, como um array ordenado de objetos {feature, status}.

Show child attributes

last_session_at

string<date-time> | null

Carimbo de data/hora da sessão mais recente

first_session_at

string<date-time> | null

Carimbo de data/hora da primeira sessão

last_activity_at

string<date-time> | null

Carimbo de data/hora da atividade mais recente neste utilizador (sessão, transação, mudança de estado, edição de dados, etc.).

​Visão geral

​Quando usar

​Dados de contacto

​Enviar uma ligação de verificação

​Notas

​Permissões

​Relacionados

Autorizações

Corpo

Resposta

Visão geral

Quando usar

Dados de contacto

Enviar uma ligação de verificação

Notas

Permissões

Relacionados