> ## 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 aggiornamento stato azienda: blocco o segnalazione > Blocca, segnala o attiva un'azienda Didit (KYB). Lo stato si applica alle sessioni KYB future e allo screening transazioni. A consumo. Prompt per l'aggiornamento dello stato dell'azienda Copia il prompt negli appunti \

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

Endpoint: PATCH https://verification.didit.me/v3/businesses/{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" (VendorBusinessStatusChoices, NOT the session enum).
\- reason (string, optional, max 1000): why the status changed. Recorded on the status-change entry in the company's Activity in the Business Console, only when the status actually changes. Webhooks do not carry it.

Status semantics:
\- ACTIVE  → normal. New KYB 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 KYB session creations for the same identifier are rejected. Flipping back to ACTIVE/FLAGGED removes the blocklist entry automatically.

curl:
curl -X PATCH 'https://verification.didit.me/v3/businesses/company-123/update-status/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"status": "BLOCKED", "reason": "Registry shows the company dissolved"}'

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

Side effects:
\- Toggles the system blocklist entry when entering/leaving BLOCKED.
\- Writes one status-change entry to the company's activity (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.
\- 403: a scoped API key without businesses write. { "detail": "This API key has no write access to companies." }
\- 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 un'[entità Business](https://docs.didit.me/it/entities/businesses/overview.md) tra `ACTIVE`, `FLAGGED` e `BLOCKED`. Consulta il [ciclo di vita delle entità](https://docs.didit.me/it/entities/lifecycle.md) per la macchina a stati completa.## Quando usarlo- **Blocca** un'azienda soggetta a sanzioni o confermata come fraudolenta. - **Segnala** un'azienda in attesa di revisione manuale. - **Sblocca** dopo la risoluzione del problema. - **Propaga i segnali esterni** provenienti dai tuoi sistemi di compliance.## Note- Valori validi: `ACTIVE`, `FLAGGED`, `BLOCKED`. - Puoi passare un parametro facoltativo `reason` (fino a 1000 caratteri) per registrare il motivo della modifica di stato. Didit lo conserva nella voce di modifica dello stato nella sezione **Attività** dell'azienda nella Business Console. Viene registrato solo quando lo stato cambia effettivamente. - Tutte le nuove sessioni di Verifica aziendale (KYB) delle aziende `BLOCKED` vengono rifiutate automaticamente, così come tutte le nuove transazioni, anche quando l'azienda compare come controparte. - Emette `business.status.updated` con `previous_status` e `status`. Il webhook non contiene `reason`.## Applicazione| Stato | Nuove sessioni di Verifica aziendale (KYB) | Transazioni che coinvolgono questa azienda | | - | - | - | | `ACTIVE` | Flusso normale | Flusso normale | | `FLAGGED` | Instradata a `IN_REVIEW` | Può essere sottoposta automaticamente a escalation tramite 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 **Aziende** (`businesses`). 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 delle entità](https://docs.didit.me/it/entities/lifecycle.md) - [Blocklist delle aziende](https://docs.didit.me/it/entities/businesses/blocklist.md) - [Webhook delle entità](https://docs.didit.me/it/entities/webhooks.md) ## OpenAPI ````yaml it/openapi-25.json PATCH /v3/businesses/{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/businesses/{vendor_data}/update-status/: patch: tags: - Businesses summary: Aggiorna lo stato dell'azienda description: >- Modifica solo lo `status` del ciclo di vita di un'azienda: `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 nell'attività dell'azienda, con il `reason` facoltativo. L'invio dello stato attuale non modifica nulla e non registra alcun `reason`. Il webhook `business.status.updated` non include `reason`. operationId: update_business_status parameters: - name: vendor_data in: path required: true schema: type: string description: >- Il tuo identificatore univoco per l'azienda (stringa a formato libero, NON un UUID). example: company-123 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 in **Activity** dell'azienda nella Business Console, solo quando lo stato cambia effettivamente. I webhook non lo includono. examples: Flag: summary: Segnala l'azienda per la revisione value: status: FLAGGED Block: summary: Blocca l'azienda (aggiunge alla blocklist di sistema) value: status: BLOCKED Reactivate: summary: Riattiva l'azienda value: status: ACTIVE Block with reason: summary: Blocca l'azienda e registra il motivo value: status: BLOCKED reason: Registry shows the company dissolved responses: '200': description: >- Stato dell'azienda aggiornato. Restituisce il record aziendale completo. content: application/json: schema: $ref: '#/components/schemas/BusinessDetailItem' examples: Blocked: value: didit_internal_id: a1b2c3d4-e5f6-4890-abcd-ef1234567890 vendor_data: company-123 display_name: null legal_name: Acme Trading Ltd registration_number: '12345678' country_code: GB effective_name: Acme Trading Ltd status: BLOCKED session_count: 2 approved_count: 1 declined_count: 0 in_review_count: 1 features: KYB: Approved features_list: - feature: KYB status: Approved last_session_at: '2026-03-15T10:30:00Z' last_activity_at: '2026-03-15T10:30:00Z' first_session_at: '2026-01-10T08:00:00Z' tags: - uuid: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d name: VIP color: '#2567FF' created_at: '2026-01-10T08:00:00Z' metadata: industry: fintech updated_at: '2026-03-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. '403': description: >- Chiave API mancante, non valida o revocata, oppure la chiave non può aggiornare aziende 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: >- Nessuna azienda (non eliminata) 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/businesses/company-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.businesses.update_status( "company-123", status="FLAGGED", ) 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.businesses.updateStatus("company-123", { status: "FLAGGED", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.UpdateStatus(ctx, \"company-123\", didit.BusinessesUpdateStatusParams{\n\tStatus: \"FLAGGED\",\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.BusinessesUpdateStatusParams; import me.didit.types.EntityStatusUpdateRequest; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.businesses().updateStatus("company-123", BusinessesUpdateStatusParams.builder() .status(EntityStatusUpdateRequest.Status.of("FLAGGED")) .build()); System.out.println(result); - lang: php label: PHP source: |- businesses->updateStatus('company-123', [ 'status' => 'FLAGGED', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.businesses.update_status( "company-123", status: "FLAGGED" ) 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.Businesses.UpdateStatusAsync("company-123", new BusinessesUpdateStatusParams { Status = "FLAGGED", }); 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. BusinessDetailItem: type: object description: >- Dettagli completi dell'azienda. Estende BusinessListItem con metadati e updated_at. allOf: - $ref: '#/components/schemas/BusinessListItem' - type: object properties: metadata: type: object description: >- JSON di metadati personalizzati che hai allegato a questa azienda. Il valore predefinito è `{}`. updated_at: type: string format: date-time BusinessListItem: type: object description: Un'azienda verificata. properties: didit_internal_id: type: string format: uuid description: UUID interno stabile di Didit per questa azienda. vendor_data: type: string nullable: true description: >- Il tuo identificatore univoco per questa azienda (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 legal_name: type: string nullable: true description: Denominazione legale ufficiale dal registro o inserimento manuale registration_number: type: string nullable: true description: Numero di registrazione o costituzione dell'azienda country_code: type: string nullable: true description: Paese di costituzione (ISO 3166-1 alpha-2, ad es. `GB`, `US`). effective_name: type: string nullable: true description: >- Miglior nome disponibile: display_name se impostato, altrimenti legal_name status: type: string enum: - ACTIVE - FLAGGED - BLOCKED description: >- Stato del ciclo di vita del record aziendale (NON uno stato della sessione). `ACTIVE` è il valore predefinito, `FLAGGED` lo contrassegna per una verifica manuale, `BLOCKED` impedisce nuove sessioni per questo `vendor_data`. session_count: type: integer description: Numero totale di sessioni di verifica per questa azienda 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 features: type: object description: >- Stato aggregato per funzionalità in tutte le sessioni KYB di questa azienda. Attualmente l'unica chiave è `KYB` (lo stato del controllo aziendale nel registro). 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 (cambio di stato, aggiornamento della sessione, ecc.) tags: type: array items: type: object properties: uuid: type: string format: uuid name: type: string color: type: string description: Tag assegnati a questa azienda 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.