> ## 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.

# Aggiorna dati sessione API: correggi campi KYC e KYB

> Correggi i campi OCR di KYC, prova di residenza o KYB nelle sessioni con Didit. Tre endpoint PATCH per aggiornamenti parziali, con webhook. A consumo.



Prompt per aggiornare i dati della sessione
        Copia il prompt negli appunti



      
      

\<pre>

\`Correct OCR-extracted fields on a finished Didit verification session — KYC identity, Proof of Address, or KYB company data.

There are THREE separate PATCH endpoints. Pick the one that matches the feature record you need to fix.

1\) Update KYC identity data
PATCH https://verification.didit.me/v3/session/{session_id}/update-data/
\- Auth: x-api-key (client) or user-auth token. Privilege: write:sessions.
\- Session status must be one of Approved, Declined, In Review, Kyc Expired.
\- Session must have a captured KYC feature record.
\- Optional query / body param node_id targets a specific KYC instance in multi-step workflows (e.g. node_id=feature_ocr_2).
\- Mutable fields: document_type ("P", "ID", "DL", "RP"), document_number, personal_number, date_of_birth (ISO date), date_of_issue, expiration_date, issuing_state (ISO 3166-1 alpha-3), first_name, last_name (full_name is auto-recomputed), gender ("M"|"F"|"X"), nationality, marital_status, place_of_birth, address (free-text — triggers re-geocoding), parsed_address (nested: address_type, city, region, street_1, street_2, postal_code, country [ISO 3166-1 alpha-2]), extra_fields (object — send null on a key to remove it).

2\) Update Proof of Address (POA) data
PATCH https://verification.didit.me/v3/session/{session_id}/update-poa-data/
\- Same auth + privilege + status gate as KYC.
\- Session must have a captured POA record. node_id supported.
\- Mutable fields: issuing_state (ISO-3), document_type ("utility_bill" | "bank_statement" | "lease_agreement"), document_language (ISO 639-1), issuer, issue_date (ISO date), poa_address (free-text — triggers re-geocoding), name_on_document, poa_parsed_address (same nested shape as KYC parsed_address), extra_fields (bank_account_number, bank_iban, bank_sort_code, bank_routing_number, bank_swift_bic, bank_branch_name, bank_branch_address, document_phone_number, additional_names).

3\) Update KYB company data
PATCH https://verification.didit.me/v3/session/{session_id}/kyb/{company_uuid}/update-data/
\- Privilege: write:businesses (NOT write:sessions).
\- No status gate — KYB company data can be corrected at any time.
\- company_uuid must belong to that session_id (else 404).
\- Mutable fields: company_name, registration_number, country_code (ISO-3), incorporation_date / registration_date / dissolution_date, tax_number, legal_address (lands on registered_address), company_type, registry_status ("active" | "dissolved" | "struck_off" | "inactive" | ...), verification_status ("verified" | "failed" | "unknown"), alternative_names, nature_of_business, registered_capital, website, email, phone, legal_entity_identifier, location_of_registration, control_scheme.
\- Edits BOTH the canonical column and registry_data. user_provided_data is never touched.

4\) Skip (or re-require) a Key People party
PATCH https://verification.didit.me/v3/session/{session_id}/kyb/parties/{party_uuid}/
\- Privilege: write:businesses.
\- Body: { "is_skipped": true } to exempt the party, { "is_skipped": false } to put it back in scope.
\- party_uuid must belong to that session_id (else 404).
\- Use it when a party can no longer finish its own check - most often because the linked individual KYC session was deleted - and the KYB is stuck in Awaiting User with nothing left that can move it.
\- Independent of the role's allow_skip setting: that flag limits what the applicant may skip in the hosted flow, not what you may override.
\- requires_verification is left untouched, so the override stays visible as requires_verification: true + is_skipped: true.
\- Recomputes the Key People check and the parent session status immediately, and fires data.updated with trigger: "console_key_people_skip".

Common contract for all four:
\- PATCH semantics — only fields you send are updated. Omit a field to leave it as-is. Send null on an extra_fields key to remove it.
\- A successful update fires a data.updated webhook (with session_kind: "user" or "business"). KYB company updates carry trigger: "console_registry_edit".
\- The audit trail records changed fields, previous + new values, and (for user-auth) the actor email.

KYC curl example:
curl -X PATCH "https://verification.didit.me/v3/session/<SESSION_ID>/update-data/" \
-H "x-api-key: <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-01-01",
"issuing_state": "ESP",
"extra_fields": { "municipality": "Madrid" }
}'

Response: the updated record (KYC / POA / KYB company shape — same fields as in the session decision).

Failure modes:
\- 401 — missing or invalid credentials.
\- 403 — { "detail": "You do not have permission to perform this action." } — caller lacks write:sessions (KYC/POA) or write:businesses (KYB company).
\- 404 — { "detail": "Not found." } — session, node_id, or company_uuid not found; OR the session does not carry the feature record you are patching (no KYC / no POA / no matching company).
\- 400 — validation error: invalid country code, unknown parsed_address key, extra_fields not an object, etc. Returned as { "<field>": ["..."] }.

When NOT to use these endpoints:
\- To ask the user to retake the document → use PATCH /v3/session/{id}/update-status/ with new_status: "Resubmitted" (see /sessions-api/update-status).
\- To change entity-level data → use /v3/users/{vendor_data}/ or /v3/businesses/{vendor_data}/.
\- To edit Key People names / roles / ownership - no public API; that data is submitted through the hosted flow. Only the is_skipped flag is patchable (endpoint 4).

Side effects:
\- Changes to KYC name / DOB / nationality can re-trigger AML if AML was still running.
\- Changes to address / poa_address re-run geocoding asynchronously (failures swallowed — they never fail the update).

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

\</pre>



      
      

Incolla in

A volte l'OCR legge in modo errato un documento d'identità, una bolletta delle utenze o una voce del registro. Didit espone tre endpoint PATCH con cui puoi correggere i dati estratti senza dover rieseguire l'intera verifica.| Endpoint | Da usare quando |
| - | - |
| [`PATCH /v3/session/{id}/update-data/`](#aggiornare-i-dati-di-identità-kyc) | Correggi i valori estratti da un documento d'identità su una sessione di **Verifica degli utenti (KYC)** |
| [`PATCH /v3/session/{id}/update-poa-data/`](#aggiornare-i-dati-della-prova-di-residenza-poa) | Correggi i valori estratti da una bolletta delle utenze / estratto conto bancario / contratto di locazione su una sessione di **Verifica degli utenti (KYC)** |
| [`PATCH /v3/session/{id}/kyb/{company_uuid}/update-data/`](#aggiornare-i-dati-di-un’azienda-kyb) | Correggi i campi estratti dal registro su una sessione di **Verifica aziendale (KYB)** |
| [`PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`](#escludere-una-parte-della-sezione-key-people) | Esenta una persona appartenente alle persone chiave dalla verifica quando non può più completare il proprio controllo |Tutti e quattro accettano la tua **chiave API del client** oppure un'**intestazione di autorizzazione utente**, e tutti e quattro emettono un webhook `data.updated` in caso di successo, così il tuo sistema e le analisi a valle restano sincronizzati.## Requisiti comuni- **Autorizzazione** — chiave API del client (standard `x-api-key` / bearer `Authorization`) oppure token di autenticazione utente.
- **Privilegio** —
  * KYC e POA: `write:sessions`
  * Azienda KYB e persona chiave: `write:businesses`
- **Stato della sessione** (solo KYC / POA) — deve essere uno tra `APPROVED`, `DECLINED`, `IN_REVIEW` o `KYC_EXPIRED`. Le sessioni che non hanno ancora raggiunto uno stato idoneo alla revisione non possono essere modificate. Gli aggiornamenti dell'azienda KYB non hanno vincoli di stato.
- **Il record della funzionalità deve esistere** — puoi modificare i campi KYC solo se la sessione contiene un record KYC, i campi POA solo se contiene un record POA, e i campi dell'azienda KYB solo se la sessione include un controllo del registro.
- **Aggiornamenti parziali** — vengono modificati solo i campi che includi. Ometti un campo per lasciarlo invariato. Invia `null` per eliminare una chiave di `extra_fields`.
- **Webhook** — un aggiornamento riuscito attiva `data.updated` con `session_kind: "user"` oppure `"business"`, e il registro di audit della sessione riporta quali campi specifici sono stati modificati e da chi.## Aggiornare i dati di identità KYC**`PATCH /v3/session/{sessionId}/update-data/`**Modifica qualsiasi campo estratto dal documento d'identità. Supporta i workflow multi-istanza basati su grafo tramite il parametro di query opzionale `node_id` o il campo nel body: indica un record KYC specifico quando una sessione ha più passaggi KYC.### Campi modificabili| Campo | Note |
| - | - |
| `document_type` | Codice documento ISO: `P` (passaporto), `ID`, `DL`, `RP`. |
| `document_number` | Il numero stampato sul documento. |
| `personal_number` | Codice personale / identificativo fiscale quando stampato sul documento. |
| `date_of_birth` | Data ISO 8601. |
| `date_of_issue` / `expiration_date` | Date ISO 8601. |
| `issuing_state` | Paese di emissione, ISO 3166-1 alpha-3. |
| `first_name` / `last_name` | `full_name` viene ricalcolato automaticamente a partire da questi due campi. |
| `gender` | `M`, `F` oppure `X` quando presente. |
| `nationality` | Testo libero. |
| `marital_status` | Testo libero. |
| `place_of_birth` | Testo libero. |
| `address` | Indirizzo in testo libero dal documento. Attiva una nuova geocodifica. |
| `parsed_address` | Indirizzo strutturato: vedi la forma annidata qui sotto. |
| `extra_fields` | Campi extra arbitrari dal documento d'identità (ad esempio `blood_group`, `municipality`). Invia `null` per una chiave per rimuoverla. |`parsed_address` accetta solo queste chiavi annidate: `address_type`, `city`, `region`, `street_1`, `street_2`, `postal_code`, `country` (ISO 3166-1 **alpha-2**).### Esempio```bash theme={null}
curl -X PATCH "https://verification.didit.me/v3/session/4c5c7f3a.../update-data/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-01-01",
    "issuing_state": "ESP",
    "extra_fields": { "municipality": "Madrid" }
  }'
```Per un workflow a grafo multi-istanza, aggiungi `?node_id=feature_ocr_2` all'URL (oppure passa `"node_id": "feature_ocr_2"` nel body) per indicare un record KYC specifico.## Aggiornare i dati della Prova di residenza (POA)**`PATCH /v3/session/{sessionId}/update-poa-data/`**Modifica i campi estratti da un documento di prova di residenza. Stessi vincoli di stato e stesso privilegio degli aggiornamenti KYC. Supporta anche `node_id` per i workflow multi-istanza.### Campi modificabili| Campo | Note |
| - | - |
| `issuing_state` | Paese che ha emesso il documento, ISO 3166-1 alpha-3. |
| `document_type` | Ad esempio `utility_bill`, `bank_statement`, `lease_agreement`. |
| `document_language` | Lingua del documento secondo ISO 639-1. |
| `issuer` | Azienda di servizi, banca, locatore, ecc. |
| `issue_date` | Data ISO 8601. |
| `poa_address` | Indirizzo come stampato sul documento (testo libero). Attiva una nuova geocodifica. |
| `name_on_document` | Nome completo stampato sul documento. |
| `poa_parsed_address` | Indirizzo strutturato: stessa forma annidata del `parsed_address` KYC. |
| `extra_fields` | Campi specifici del documento: dati bancari (`bank_account_number`, `bank_iban`, `bank_sort_code`, `bank_routing_number`, `bank_swift_bic`, `bank_branch_name`, `bank_branch_address`), `document_phone_number`, `additional_names` (lista oppure `null`). |### Esempio```bash theme={null}
curl -X PATCH "https://verification.didit.me/v3/session/4c5c7f3a.../update-poa-data/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "utility_bill",
    "issuer": "Iberdrola",
    "issue_date": "2026-03-15",
    "name_on_document": "Jane Doe",
    "poa_parsed_address": {
      "street_1": "Calle Mayor 10",
      "city": "Madrid",
      "postal_code": "28013",
      "country": "ES"
    }
  }'
```## Aggiornare i dati di un'azienda KYB**`PATCH /v3/session/{sessionId}/kyb/{companyUuid}/update-data/`**Correggi i campi estratti dal registro per un'azienda KYB. L'endpoint modifica **sia** le colonne canoniche dell'azienda sia `registry_data`, così la vista "Extracted from Registry" della console riflette le tue correzioni. `user_provided_data` (ciò che l'utente finale ha confermato nel flusso ospitato) non viene modificato. `last_console_edit_at` viene aggiornato e viene inviato un webhook `data.updated` con `trigger: "console_registry_edit"`.### Requisiti- **Privilegio**: `write:businesses` (diverso dal privilegio KYC / POA).
- Il `companyUuid` nell'URL deve appartenere al `sessionId` indicato, altrimenti ottieni un 404.
- Nessun vincolo sullo stato della sessione: i dati dell'azienda KYB possono essere corretti in qualsiasi momento.### Campi modificabili| Campo | Note |
| - | - |
| `company_name` | Ragione sociale. |
| `registration_number` | Numero di registrazione ufficiale. |
| `country_code` | Paese di costituzione, ISO 3166-1 alpha-3. |
| `incorporation_date` / `registration_date` / `dissolution_date` | Date ISO 8601. |
| `tax_number` | Identificativo fiscale. |
| `legal_address` | Alias di `registered_address`: finisce nella colonna canonica `registered_address`. |
| `company_type` | Ltd / LLC / PLC / SA / GmbH / SL ecc. |
| `registry_status` | `active`, `dissolved`, `struck_off`, `inactive` ecc. |
| `verification_status` | `verified`, `failed`, `unknown`. |
| `alternative_names` | Nomi commerciali, precedenti denominazioni, DBA. |
| `nature_of_business` | Breve descrizione. |
| `registered_capital` | Capitale autorizzato / emesso. |
| `website`, `email`, `phone` | Dati di contatto. |
| `legal_entity_identifier` | LEI. |
| `location_of_registration` | Città / suddivisione amministrativa. |
| `control_scheme` | Schema di governance, quando il registro lo espone. |I campi omessi restano invariati. Ogni campo inviato viene scritto nella colonna canonica (quando esiste) e unito a `registry_data`. Le date vengono serializzate come stringhe ISO 8601 quando sono unite a `registry_data`.### Esempio```bash theme={null}
curl -X PATCH "https://verification.didit.me/v3/session/bs-01HJX1.../kyb/f7a9c1b2-4e6d.../update-data/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Corporation Limited",
    "registration_number": "12345678",
    "registry_status": "active",
    "legal_address": "1 Main Street, London EC1A 1AA, United Kingdom",
    "alternative_names": "Acme Ltd, Acme Group"
  }'
```Risposta: l'oggetto completo dell'azienda KYB, con la stessa struttura di `registry_checks[].company` nella [decisione della sessione](https://docs.didit.me/it/sessions-api/retrieve-session.md#verifica-aziendale-kyb).## Escludere una parte della sezione Key People**`PATCH /v3/session/{sessionId}/kyb/parties/{partyUuid}/`**Esenta una persona della sezione Key People dalla verifica: è la via d'uscita per una persona che non può mai completare il proprio controllo. La causa più comune è una sessione figlia eliminata: una volta eliminata la KYC individuale assegnata a un titolare effettivo o a un amministratore, il suo stato resta bloccato e non potrà mai concludersi, quindi la KYB non ha più nulla che possa spostarla da `Awaiting User`. Escludere la persona la rimuove dall'aggregazione Key People, il controllo viene ricalcolato immediatamente e la sessione può concludersi ed essere approvata o rifiutata.### Requisiti- **Privilegio**: `write:businesses`.
- Il `partyUuid` nell'URL deve appartenere al `sessionId` indicato, altrimenti ottieni un 404.
- **Non è vincolato da `allow_skip`.** Quell'impostazione del ruolo limita ciò che il richiedente può escludere mentre compila la schermata Key People ospitata; questo endpoint è l'override dell'operatore, quindi funziona anche sui ruoli che il richiedente non avrebbe potuto escludere.### Corpo della richiesta| Campo | Tipo | Note |
| - | - | - |
| `is_skipped` | boolean | `true` esenta la persona; `false` la reinserisce nel controllo e la verifica torna ad attendere la persona. |`requires_verification` viene volutamente lasciato invariato, quindi una persona per cui è stato applicato l'override risulta con `requires_verification: true` **e** `is_skipped: true`: il record mostra comunque che le regole richiedevano un controllo.### Esempio```bash theme={null}
curl -X PATCH "https://verification.didit.me/v3/session/bs-01HJX1.../kyb/parties/0a3f1e2c-7c2f.../" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_skipped": true }'
```Risposta: la persona aggiornata, con la stessa struttura di un elemento di `key_people_checks[].submitted.parties[]` nella [decisione della sessione](https://docs.didit.me/it/business-verification/response-schema.md#key_people_checks).Viene inviato un webhook `data.updated` con `trigger: "console_key_people_skip"`.> [!NOTE]
>
> Una persona la cui sessione figlia è stata eliminata viene segnalata nel payload della decisione con
> `kyc_session_deleted: true` (oppure `kyb_sub_session_deleted: true` per le persone giuridiche),
> e il suo `kyc_session_url` / `kyb_sub_session_url` viene restituito come
> `null` perché il collegamento non è più valido. L'eliminazione di una sessione figlia non approva
> da sola la persona: il controllo Key People passa a `In Review`, così che sia una persona a decidere.## Cosa succede dopo un aggiornamento- **Webhook**: `data.updated` viene inviato per la sessione, con il `session_kind` della sessione nel payload (`"user"` o `"business"`). Iscriviti una sola volta a livello di destinazione e smista in base a `session_kind`.
- **Registro di controllo**: la sessione registra esattamente quali campi sono cambiati, i valori precedenti e quelli nuovi e (per le chiamate con autenticazione utente) l'email dell'attore. Visibile nella scheda Events della console.
- **Rigeocodifica dell'indirizzo**: per gli aggiornamenti KYC e POA che modificano `address` / `poa_address`, Didit esegue la rigeocodifica in background. Gli errori vengono ignorati, così l'aggiornamento non fallisce mai per un problema di geocodifica.
- **Rivalutazione AML**: gli aggiornamenti KYC che modificano nome / data di nascita / nazionalità possono rilanciare lo screening AML se lo screening AML sulla sessione non era ancora terminato. I risultati compaiono nella decisione della sessione.## Quando non usare questi endpoint- **Ripetere l'intera verifica**: se il cliente deve rifare la foto del documento d'identità o ricaricare un documento, usa [update-status](https://docs.didit.me/it/sessions-api/update-status.md) per portare la sessione in `Resubmitted`.
- **Modificare i campi del profilo dell'entità User o Business**: usa [`PATCH /v3/users/{vendor_data}/`](https://docs.didit.me/it/management-api/users/update) oppure [`PATCH /v3/businesses/{vendor_data}/`](https://docs.didit.me/it/management-api/businesses/update); questi endpoint aggiornano i dati a livello di entità, non a livello di sessione.
- **Modificare i dettagli delle persone Key People**: non esiste un'API pubblica per modificare nome, ruoli o assetto proprietario di una persona; questi dati vengono inviati tramite il flusso ospitato. L'unico campo modificabile è `is_skipped` (vedi [Escludere una parte della sezione Key People](#escludere-una-parte-della-sezione-key-people)).## Errori| Stato | Significato |
| - | - |
| `401` | Credenziali mancanti o non valide. |
| `403` | Il chiamante non dispone del privilegio richiesto (`write:sessions` o `write:businesses`). |
| `404` | Sessione non trovata, oppure la sessione non contiene il record che stai modificando (nessun KYC, nessun POA, nessuna azienda corrispondente, nessun soggetto corrispondente oppure un soggetto che appartiene a un'altra sessione). |
| `400` | Errore di validazione: codice paese non valido, chiave `parsed_address` sconosciuta, `extra_fields` che non è un oggetto, ecc. |## Passaggi successivi> [card] [Recupera la sessione](https://docs.didit.me/it/sessions-api/retrieve-session.md)
>
> Recupera la decisione completa per vedere i campi aggiornati.> [card] [Aggiorna lo stato](https://docs.didit.me/it/sessions-api/update-status.md)
>
> Approva, rifiuta o riapri una sessione dopo una correzione dei dati.> [card] [Webhook](https://docs.didit.me/it/integration/webhooks.md)
>
> Iscriviti agli eventi `data.updated`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.