> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # API per aggiornare lo stato utente: blocco o segnalazione > Blocca, segnala o attiva un utente vendor di Didit. Lo stato si applica alle future sessioni KYC e allo screening delle transazioni. Prompt per l'aggiornamento dello stato utente Copia il prompt negli appunti \

\`Goal: Flip ONLY the lifecycle status of a Didit User entity. Use the full PATCH /v3/users/{vendor_data}/ when you also need to touch other fields.

Endpoint: PATCH https://verification.didit.me/v3/users/{vendor_data}/update-status/
Auth header: x-api-key: 
Content-Type: application/json

Path param:
\- vendor_data (string, REQUIRED) — free-form string, NOT a UUID. URL-encode.

Request body:
\- status (enum, REQUIRED) — "ACTIVE" | "FLAGGED" | "BLOCKED" (VendorUserStatusChoices, NOT the session enum).
\- reason (string, optional, max 1000): why the status changed. Recorded as the comment of the STATUS_CHANGED entry in the user's activity (comments[].comment), only when the status actually changes. Webhooks do not carry it.

Status semantics:
\- ACTIVE  → normal. New sessions allowed for this vendor_data.
\- FLAGGED → still accepted, highlighted in Console for manual review; filterable with ?status=FLAGGED.
\- BLOCKED → terminal. Adds vendor_data to the system blocklist. Subsequent session creations for the same identifier are rejected with a blocklist hit. Flipping back to ACTIVE/FLAGGED removes the blocklist entry automatically.

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", "reason": "Chargeback fraud pattern confirmed"}'

Response 200: full updated UserDetailItem (same shape as GET /v3/users/{vendor_data}/). See /reference/data-models.

Side effects:
\- Toggles the system blocklist entry when entering/leaving BLOCKED.
\- Writes one STATUS_CHANGED entry to the user's comments activity log (actor = API key identity), with reason as its comment.
\- Idempotent — re-sending the same status is a no-op (no extra audit row, no extra blocklist toggle).

Failure modes:
\- 400 — validation:
\{ "status": "This field is required." }
\{ "status": "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" }
\{ "reason": ["Ensure this field has no more than 1000 characters."] }
\- 401 — missing/invalid x-api-key. { "detail": "Authentication credentials were not provided." }
\- 403 — the API key is revoked or is not valid for this application. { "detail": "You do not have permission to perform this action." }
\- 403: a scoped API key without users write. { "detail": "This API key has no write access to people." }
\- 404 — vendor_data not found (or deleted). { "detail": "Not found." }
\- 429 — rate-limited.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\
Incolla in ## PanoramicaSposta una [entità User](https://docs.didit.me/it/entities/users/overview.md) tra `ACTIVE`, `FLAGGED` e `BLOCKED`. Consulta il [ciclo di vita dell'entità](https://docs.didit.me/it/entities/lifecycle.md) 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 |## AutorizzazioniIl segreto primario e le [chiavi API](https://docs.didit.me/it/console/api-keys.md) 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](https://docs.didit.me/it/console/roles-permissions.md) della Console determinano cosa può fare un membro del team nella Console. Non vengono valutati per le richieste con chiave API.## Correlati- [Ciclo di vita dell'entità](https://docs.didit.me/it/entities/lifecycle.md) - [Blocklist degli utenti](https://docs.didit.me/it/entities/users/blocklist.md) - [Webhook delle entità](https://docs.didit.me/it/entities/webhooks.md) ## OpenAPI ````yaml it/openapi-25.json PATCH /v3/users/{vendor_data}/update-status/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/users/{vendor_data}/update-status/: patch: tags: - Users summary: Aggiorna lo stato dell'utente description: >- Modifica solo lo `status` del ciclo di vita di un utente: `ACTIVE`, `FLAGGED` o `BLOCKED` (non gli stati della sessione). `BLOCKED` aggiunge il `vendor_data` alla blocklist di sistema; passare a uno stato diverso da `BLOCKED` rimuove tale voce. Ogni modifica viene registrata come attività `STATUS_CHANGED` sull'utente, con il `reason` facoltativo come relativo `comment`. L'invio dello stato attuale non modifica nulla e non registra alcun `reason`. Il webhook `user.status.updated` non include `reason`. operationId: update_user_status parameters: - name: vendor_data in: path required: true schema: type: string description: Il tuo identificatore univoco per l'utente. requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/EntityStatusUpdateRequest' - type: object properties: reason: type: string nullable: true maxLength: 1000 description: >- 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. examples: Activate: summary: Riattiva l'utente value: status: ACTIVE Flag: summary: Segnala l'utente per la revisione value: status: FLAGGED Block: summary: Blocca l'utente (aggiunge alla blocklist di sistema) value: status: BLOCKED Block with reason: summary: Blocca l'utente e registra il motivo value: status: BLOCKED reason: Chargeback fraud pattern confirmed responses: '200': description: Stato dell'utente aggiornato. Restituisce il record utente completo. content: application/json: schema: $ref: '#/components/schemas/UserDetailItem' examples: Blocked: value: 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:///... 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' '400': description: >- `status` mancante o non valido, oppure un `reason` superiore a 1000 caratteri. content: application/json: examples: Missing status: value: status: - This field is required. Bad status: value: status: - >- Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED Reason too long: value: reason: - Ensure this field has no more than 1000 characters. '401': description: >- Nessuna credenziale fornita. Le richieste ai percorsi `/v3/users/*` senza un'intestazione `x-api-key` (o token `Authorization: Bearer`) vengono rifiutate dal middleware di autenticazione prima di raggiungere l'API. content: application/json: examples: Missing credentials: value: detail: >- You must be authenticated with a valid access token to access this endpoint. '403': description: >- La chiave non può aggiornare gli utenti per questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '404': description: >- Nessun utente (non eliminato) con il `vendor_data` fornito esiste per questa applicazione. content: application/json: examples: Not found: value: detail: Not found. '429': description: >- Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`. content: application/json: examples: Rate limited: value: detail: Request was throttled. Expected available in 30 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- 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"}' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.users.update_status( "user-123", status="ACTIVE", ) print(result) - lang: javascript label: Node.js source: |- 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); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.UpdateStatus(ctx, \"user-123\", didit.UsersUpdateStatusParams{\n\tStatus: \"ACTIVE\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- 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); - lang: php label: PHP source: |- users->updateStatus('user-123', [ 'status' => 'ACTIVE', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.users.update_status( "user-123", status: "ACTIVE" ) puts result.to_h - lang: csharp label: .NET source: >- 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)); components: schemas: EntityStatusUpdateRequest: type: object required: - status properties: status: type: string enum: - ACTIVE - FLAGGED - BLOCKED description: >- Nuovo stato del ciclo di vita. `BLOCKED` aggiunge inoltre il `vendor_data` alla blocklist di sistema. UserDetailItem: type: object description: >- Dettaglio completo dell'utente. Estende UserListItem con metadati, commenti e updated_at. allOf: - $ref: '#/components/schemas/UserListItem' - type: object properties: metadata: type: object description: >- JSON di metadati personalizzati che hai allegato a questo utente. Il valore predefinito è `{}`. tags: type: array description: >- Assegnazioni dei tag. NOTA: nelle risposte di dettaglio ogni voce è un oggetto *collegamento* del tag (`{uuid, tag: {...}, added_by_email, added_by_name, created_at}`), a differenza della struttura piatta `{uuid, name, color}` usata nelle risposte di elenco. items: type: object properties: uuid: type: string format: uuid description: UUID dell'assegnazione del tag (non del tag stesso). tag: type: object properties: uuid: type: string format: uuid name: type: string color: type: string description: type: string nullable: true source: type: string enum: - didit - custom created_at: type: string format: date-time updated_at: type: string format: date-time added_by_email: type: string nullable: true added_by_name: type: string nullable: true created_at: type: string format: date-time comments: type: array items: type: object properties: uuid: type: string format: uuid comment_type: type: string enum: - COMMENT - STATUS_CHANGED - METADATA_UPDATED - TAG_ADDED - TAG_REMOVED - PROFILE_UPDATED comment: type: string nullable: true actor_email: type: string nullable: true actor_name: type: string nullable: true previous_status: type: string nullable: true enum: - ACTIVE - FLAGGED - BLOCKED - null new_status: type: string nullable: true enum: - ACTIVE - FLAGGED - BLOCKED - null previous_value: type: object nullable: true description: Valori precedenti dei campi per le voci PROFILE_UPDATED. new_value: type: object nullable: true description: Nuovi valori dei campi per le voci PROFILE_UPDATED. changed_fields: type: array items: type: string description: Nomi dei campi modificati da una voce PROFILE_UPDATED. metadata: type: object nullable: true mentioned_emails: type: array items: type: string created_at: type: string format: date-time description: >- Registro delle attività e commenti per questo utente (modifiche di stato, modifiche al profilo, note manuali). updated_at: type: string format: date-time UserListItem: type: object description: Un utente verificato. properties: didit_internal_id: type: string format: uuid description: UUID interno stabile di Didit per questo utente. vendor_data: type: string nullable: true description: >- 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: type: string nullable: true description: Nome visualizzato personalizzato impostato da te full_name: type: string nullable: true description: Nome completo estratto dai documenti verificati date_of_birth: type: string format: date nullable: true effective_name: type: string nullable: true description: >- Miglior nome disponibile: display_name se impostato, altrimenti full_name status: type: string enum: - ACTIVE - FLAGGED - BLOCKED description: >- 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`. portrait_image_url: type: string nullable: true description: >- URL prefirmato della foto ritratto dell'utente (scade dopo alcune ore) session_count: type: integer description: Numero totale di sessioni di verifica per questo utente approved_count: type: integer description: Numero di sessioni approvate declined_count: type: integer description: Numero di sessioni rifiutate in_review_count: type: integer description: Numero di sessioni in revisione issuing_states: type: array items: type: string description: >- 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: type: array items: type: string description: >- Indirizzi email verificati raccolti dalle sessioni approvate di questo utente, ad es. `["john@example.com"]`. approved_phones: type: array items: type: string description: >- Numeri di telefono verificati raccolti dalle sessioni approvate di questo utente, ad es. `["+14155551234"]`. features: type: object description: >- 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: type: array items: type: object properties: feature: type: string status: type: string description: >- Gli stessi dati di `features`, sotto forma di array ordinato di oggetti `{feature, status}`. last_session_at: type: string format: date-time nullable: true description: Timestamp della sessione più recente first_session_at: type: string format: date-time nullable: true description: Timestamp della prima sessione last_activity_at: type: string format: date-time nullable: true description: >- Timestamp dell'attività più recente su questo utente (sessione, transazione, cambio di stato, modifica dei dati, ecc.). tags: type: array items: type: object properties: uuid: type: string format: uuid name: type: string color: type: string description: Tag assegnati a questo utente created_at: type: string format: date-time securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.