API per aggiornare lo stato utente: blocco o segnalazione

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"
}

Panoramica

Sposta una entità User tra ACTIVE, FLAGGED e BLOCKED. Consulta il ciclo di vita dell’entità per la macchina a stati completa.

Quando usarlo

Bloccare un utente dopo aver confermato una frode o una violazione di compliance.
Contrassegnare un utente in attesa di revisione manuale senza bloccarlo in modo definitivo.
Sbloccare un utente dopo il completamento delle azioni correttive.
Propagare segnali esterni: ad esempio, quando il tuo motore antifrode assegna a un utente un punteggio superiore a una soglia, spostalo in FLAGGED tramite questo endpoint.

Note

Valori validi: ACTIVE, FLAGGED, BLOCKED. I valori non validi restituiscono 400.
Puoi passare un reason facoltativo (fino a 1000 caratteri) per registrare il motivo della modifica di stato. Didit lo conserva come commento della voce di modifica dello stato nell’attività della persona: comments[].comment sull’utente e Attività nella Business Console. Viene registrato solo quando lo stato cambia effettivamente.
Gli utenti BLOCKED vedono rifiutate automaticamente tutte le nuove sessioni e tutte le nuove transazioni.
Emette un webhook user.status.updated con previous_status e status. Il webhook non contiene reason.

Applicazione

Stato	Effetto sulle nuove sessioni	Effetto sulle nuove transazioni
`ACTIVE`	Flusso normale	Flusso normale
`FLAGGED`	Consentita ma instradata verso `IN_REVIEW`	Consentita; può essere sottoposta automaticamente a un’escalation in base alle regole
`BLOCKED`	Rifiutata automaticamente	Rifiutata automaticamente

Autorizzazioni

Il segreto primario e le chiavi API con accesso completo possono sempre chiamare questo endpoint. Una chiave con accesso personalizzato necessita dell’autorizzazione di scrittura su Persone (users). Una chiave limitata ad alcuni workflow o alle sessioni approvate non può raggiungere questo endpoint. I ruoli e le autorizzazioni della Console determinano cosa può fare un membro del team nella Console. Non vengono valutati per le richieste con chiave API.

Correlati

Autorizzazioni

x-api-key

string

header

obbligatorio

La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys.

Parametri del percorso

vendor_data

string

obbligatorio

Il tuo identificatore univoco per l'utente.

Corpo

application/json

status

enum<string>

obbligatorio

Nuovo stato del ciclo di vita. BLOCKED aggiunge inoltre il vendor_data alla blocklist di sistema.

Opzioni disponibili:

ACTIVE,

FLAGGED,

BLOCKED

reason

string | null

Il motivo per cui lo stato è cambiato. Registrato nella voce di cambio di stato dell'attività dell'utente (comments[].comment e Activity nella Business Console), solo quando lo stato cambia effettivamente. I webhook non lo includono.

Maximum string length: 1000

Risposta

Stato dell'utente aggiornato. Restituisce il record utente completo.

Dettaglio completo dell'utente. Estende UserListItem con metadati, commenti e updated_at.

didit_internal_id

string<uuid>

UUID interno stabile di Didit per questo utente.

vendor_data

string | null

Il tuo identificatore univoco per questo utente (passato durante la creazione delle sessioni). Può essere null se non è stato fornito alcun identificatore del fornitore.

display_name

string | null

Nome visualizzato personalizzato impostato da te

full_name

string | null

Nome completo estratto dai documenti verificati

date_of_birth

string<date> | null

effective_name

string | null

Miglior nome disponibile: display_name se impostato, altrimenti full_name

status

enum<string>

Stato del ciclo di vita del record utente (NON uno stato della sessione). ACTIVE è il valore predefinito, FLAGGED contrassegna l'utente per una verifica manuale, BLOCKED impedisce nuove sessioni per questo vendor_data.

Opzioni disponibili:

ACTIVE,

FLAGGED,

BLOCKED

portrait_image_url

string | null

URL prefirmato della foto ritratto dell'utente (scade dopo alcune ore)

session_count

integer

Numero totale di sessioni di verifica per questo utente

approved_count

integer

Numero di sessioni approvate

declined_count

integer

Numero di sessioni rifiutate

in_review_count

integer

Numero di sessioni in revisione

issuing_states

string[]

Codici ISO 3166-1 alpha-3 dei paesi di emissione rilevati nei documenti d'identità approvati di questo utente, ad es. ["USA", "ESP"]. Array vuoto se assenti.

approved_emails

string[]

Indirizzi email verificati raccolti dalle sessioni approvate di questo utente, ad es. ["john@example.com"].

approved_phones

string[]

Numeri di telefono verificati raccolti dalle sessioni approvate di questo utente, ad es. ["+14155551234"].

features

object

Stato aggregato per funzionalità in tutte le sessioni di questo utente. Chiavi possibili: ID_VERIFICATION, NFC, LIVENESS, FACE_MATCH, POA, QUESTIONNAIRE, EMAIL_VERIFICATION, PHONE, AML, IP_ANALYSIS, AGE_ESTIMATION, DATABASE_VALIDATION. Valori possibili: Approved, Declined, In Review, Not Finished, Resub Requested.

features_list

object[]

Gli stessi dati di features, sotto forma di array ordinato di oggetti {feature, status}.

Show child attributes

last_session_at

string<date-time> | null

Timestamp della sessione più recente

first_session_at

string<date-time> | null

Timestamp della prima sessione

last_activity_at

string<date-time> | null

Timestamp dell'attività più recente su questo utente (sessione, transazione, cambio di stato, modifica dei dati, ecc.).

​Panoramica

​Quando usarlo

​Note

​Applicazione

​Autorizzazioni

​Correlati

Autorizzazioni

Parametri del percorso

Corpo

Risposta

Panoramica

Quando usarlo

Note

Applicazione

Autorizzazioni

Correlati