Atualizar status do usuário na API: bloquear ou sinalizar

curl

curl -X PATCH 'https://verification.didit.me/v3/users/user-abc-123/update-status/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"status": "BLOCKED"}'

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.users.updateStatus("user-123", {
  status: "ACTIVE",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Users.UpdateStatus(ctx, "user-123", didit.UsersUpdateStatusParams{
	Status: "ACTIVE",
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.EntityStatusUpdateRequest;
import me.didit.types.UsersUpdateStatusParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.users().updateStatus("user-123", UsersUpdateStatusParams.builder()
        .status(EntityStatusUpdateRequest.Status.of("ACTIVE"))
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->users->updateStatus('user-123', [
    'status' => 'ACTIVE',
]);
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.UpdateStatusAsync("user-123", new UsersUpdateStatusParams
{
    Status = "ACTIVE",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418",
  "vendor_data": "user-abc-123",
  "display_name": null,
  "full_name": "John Michael Doe",
  "date_of_birth": "1990-05-15",
  "effective_name": "John Michael Doe",
  "status": "BLOCKED",
  "metadata": {
    "tier": "premium",
    "source": "website"
  },
  "portrait_image_url": "https://<media-host>/...",
  "session_count": 3,
  "approved_count": 2,
  "declined_count": 0,
  "in_review_count": 1,
  "issuing_states": [
    "USA"
  ],
  "approved_emails": [
    "john@example.com"
  ],
  "approved_phones": [
    "+14155551234"
  ],
  "features": {
    "ID_VERIFICATION": "Approved",
    "LIVENESS": "Approved",
    "FACE_MATCH": "Approved",
    "AML": "Approved"
  },
  "features_list": [
    {
      "feature": "ID_VERIFICATION",
      "status": "Approved"
    },
    {
      "feature": "LIVENESS",
      "status": "Approved"
    },
    {
      "feature": "FACE_MATCH",
      "status": "Approved"
    },
    {
      "feature": "AML",
      "status": "Approved"
    }
  ],
  "last_session_at": "2025-06-15T10:30:00Z",
  "last_activity_at": "2025-06-15T10:30:00Z",
  "first_session_at": "2025-06-01T08:00:00Z",
  "tags": [
    {
      "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "tag": {
        "uuid": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
        "name": "VIP",
        "color": "#2567FF",
        "description": null,
        "source": "custom",
        "created_at": "2025-05-01T09:00:00Z",
        "updated_at": "2025-05-01T09:00:00Z"
      },
      "added_by_email": "analyst@acme.com",
      "added_by_name": "Jane Analyst",
      "created_at": "2025-06-02T11:00:00Z"
    }
  ],
  "comments": [
    {
      "uuid": "c1111111-2222-4333-8444-555555555555",
      "comment_type": "STATUS_CHANGED",
      "comment": "Chargeback fraud pattern confirmed",
      "actor_email": null,
      "actor_name": null,
      "previous_status": "ACTIVE",
      "new_status": "BLOCKED",
      "previous_value": null,
      "new_value": null,
      "changed_fields": [],
      "metadata": null,
      "mentioned_emails": [],
      "created_at": "2025-06-15T10:30:00Z"
    }
  ],
  "created_at": "2025-06-01T08:00:00Z",
  "updated_at": "2025-06-15T10:30:00Z"
}

PATCH

users

{vendor_data}

update-status

curl

curl -X PATCH 'https://verification.didit.me/v3/users/user-abc-123/update-status/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"status": "BLOCKED"}'

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.users.updateStatus("user-123", {
  status: "ACTIVE",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Users.UpdateStatus(ctx, "user-123", didit.UsersUpdateStatusParams{
	Status: "ACTIVE",
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.EntityStatusUpdateRequest;
import me.didit.types.UsersUpdateStatusParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.users().updateStatus("user-123", UsersUpdateStatusParams.builder()
        .status(EntityStatusUpdateRequest.Status.of("ACTIVE"))
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->users->updateStatus('user-123', [
    'status' => 'ACTIVE',
]);
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.UpdateStatusAsync("user-123", new UsersUpdateStatusParams
{
    Status = "ACTIVE",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418",
  "vendor_data": "user-abc-123",
  "display_name": null,
  "full_name": "John Michael Doe",
  "date_of_birth": "1990-05-15",
  "effective_name": "John Michael Doe",
  "status": "BLOCKED",
  "metadata": {
    "tier": "premium",
    "source": "website"
  },
  "portrait_image_url": "https://<media-host>/...",
  "session_count": 3,
  "approved_count": 2,
  "declined_count": 0,
  "in_review_count": 1,
  "issuing_states": [
    "USA"
  ],
  "approved_emails": [
    "john@example.com"
  ],
  "approved_phones": [
    "+14155551234"
  ],
  "features": {
    "ID_VERIFICATION": "Approved",
    "LIVENESS": "Approved",
    "FACE_MATCH": "Approved",
    "AML": "Approved"
  },
  "features_list": [
    {
      "feature": "ID_VERIFICATION",
      "status": "Approved"
    },
    {
      "feature": "LIVENESS",
      "status": "Approved"
    },
    {
      "feature": "FACE_MATCH",
      "status": "Approved"
    },
    {
      "feature": "AML",
      "status": "Approved"
    }
  ],
  "last_session_at": "2025-06-15T10:30:00Z",
  "last_activity_at": "2025-06-15T10:30:00Z",
  "first_session_at": "2025-06-01T08:00:00Z",
  "tags": [
    {
      "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "tag": {
        "uuid": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
        "name": "VIP",
        "color": "#2567FF",
        "description": null,
        "source": "custom",
        "created_at": "2025-05-01T09:00:00Z",
        "updated_at": "2025-05-01T09:00:00Z"
      },
      "added_by_email": "analyst@acme.com",
      "added_by_name": "Jane Analyst",
      "created_at": "2025-06-02T11:00:00Z"
    }
  ],
  "comments": [
    {
      "uuid": "c1111111-2222-4333-8444-555555555555",
      "comment_type": "STATUS_CHANGED",
      "comment": "Chargeback fraud pattern confirmed",
      "actor_email": null,
      "actor_name": null,
      "previous_status": "ACTIVE",
      "new_status": "BLOCKED",
      "previous_value": null,
      "new_value": null,
      "changed_fields": [],
      "metadata": null,
      "mentioned_emails": [],
      "created_at": "2025-06-15T10:30:00Z"
    }
  ],
  "created_at": "2025-06-01T08:00:00Z",
  "updated_at": "2025-06-15T10:30:00Z"
}

Visão geral

Move uma entidade User entre ACTIVE, FLAGGED e BLOCKED. Consulte o ciclo de vida das entidades para ver a máquina de estados completa.

Quando usar

Bloquear um usuário depois de confirmar uma fraude ou uma violação de conformidade.
Sinalizar um usuário pendente de revisão manual, sem bloqueá-lo completamente.
Desbloquear um usuário após a correção bem-sucedida do problema.
Propagar sinais externos: por exemplo, quando o seu próprio mecanismo antifraude atribui a um usuário uma pontuação acima de um limiar, mova-o para FLAGGED por meio deste endpoint.

Observações

Valores válidos: ACTIVE, FLAGGED, BLOCKED. Valores inválidos retornam 400.
Envie um reason opcional (até 1000 caracteres) para registrar o motivo da mudança de status. A Didit o guarda como o comentário do registro de mudança de status na atividade da pessoa: comments[].comment no usuário e Activity no Business Console. Ele só é registrado quando o status realmente muda.
Usuários BLOCKED têm todas as novas sessões recusadas automaticamente e todas as novas transações recusadas automaticamente.
Emite um webhook user.status.updated com previous_status e status. O webhook não inclui reason.

Aplicação de regras

Status	Efeito nas novas sessões	Efeito nas novas transações
`ACTIVE`	Fluxo normal	Fluxo normal
`FLAGGED`	Permitidas, mas encaminhadas para `IN_REVIEW`	Permitidas; podem ser escaladas automaticamente dependendo das regras
`BLOCKED`	Recusadas automaticamente	Recusadas automaticamente

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). 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 determinam 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.

Parâmetros de caminho

vendor_data

string

obrigatório

Seu identificador exclusivo do usuário.

Corpo

application/json

status

enum<string>

obrigatório

Novo status do ciclo de vida. BLOCKED também adiciona o vendor_data à lista de bloqueio do sistema.

Opções disponíveis:

ACTIVE,

FLAGGED,

BLOCKED

reason

string | null

Por que o status mudou. Registrado na entrada de mudança de status na atividade do usuário (comments[].comment e Activity no Business Console), apenas quando o status realmente muda. Os webhooks não o incluem.

Maximum string length: 1000

Resposta

Status do usuário atualizado. Retorna o registro completo do usuário.

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

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

​Observações

​Aplicação de regras

​Permissões

​Relacionados

Autorizações

Parâmetros de caminho

Corpo

Resposta

Visão geral

Quando usar

Observações

Aplicação de regras

Permissões

Relacionados