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

# Schema di risposta KYB: payload della decisione (Rif.)

> Schema annotato della decisione KYB di Didit: registro, persone chiave, titolari effettivi, documenti, screening AML. Da $2.00 per controllo.

Questa pagina documenta il payload completo restituito da [`GET /v3/session/{id}/decision/`](https://docs.didit.me/it/sessions-api/retrieve-session) per una sessione di Verifica aziendale (KYB). L'endpoint è unificato: quando passi un `session_id` di tipo business, la risposta contiene `session_kind: "business"` e gli array di funzionalità specifici per le aziende descritti sotto.

## Struttura di primo livello

```json theme={null}
{
  "session_id": "bs_01H...",
  "session_kind": "business",
  "session_number": 89,
  "session_url": "https://verify.didit.me/...",
  "status": "Approved",
  "status_override": null,
  "workflow_id": "wf_kyb_standard",
  "features": ["KYB_REGISTRY", "AML", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE"],
  "vendor_data": "biz-acme-001",
  "metadata": { },
  "callback": null,

  "registry_checks": [ ... ],
  "aml_screenings": [ ... ],
  "document_verifications": [ ... ],
  "key_people_checks": [ ... ],

  "phone_verifications": null,
  "email_verifications": null,
  "questionnaire_responses": null,
  "ip_analyses": null,

  "reviews": [ ],
  "decision_trace": { ... },
  "linked_records": null,
  "contact_details": { ... },
  "expected_details": null,
  "created_at": "...",
  "expires_at": "..."
}
```

Tutti gli array di funzionalità sono multi-istanza: ogni elemento rappresenta un nodo di un workflow a grafo. Null indica che la funzionalità non era presente nel workflow di questa sessione.

## Campi di primo livello comuni

| Campo | Tipo | Descrizione |
| - | - | - |
| `session_id` | UUID | Identificatore univoco della sessione |
| `session_kind` | enum | Sempre `"business"` per le sessioni KYB |
| `session_number` | int | Numero progressivo all'interno dell'applicazione |
| `session_url` | URL | Link di verifica ospitato |
| `status` | enum | Stato complessivo della sessione (vedi [stati](https://docs.didit.me/it/business-verification/statuses.md)) |
| `status_override` | object o null | `{ overridden_at, automatic_status }` quando un revisore ha impostato `status` manualmente, in contrasto con quello che la piattaforma avrebbe impostato (per esempio approvare un'azienda mentre una verifica collegata di una persona chiave è stata rifiutata). `null` quando lo stato è quello automatico. Usalo per distinguere un'approvazione manuale da una automatica |
| `decision_trace` | object | Come è stata raggiunta la decisione: `status`, `decided_by` (`manual`, `automatic` o `investigator`), `decided_at`, `automatic_status`, `terminal_node_id`, `actor`, `warning_counts` e `status_warnings` (gli avvisi che hanno impostato lo stato) |
| `linked_records` | object o null | Un riepilogo di altri record collegati alla sessione. `null` quando non c'è nulla da mostrare |
| `workflow_id` | UUID | Workflow che ha guidato questa sessione |
| `features` | array di stringhe | Identificatori delle funzionalità eseguite dal workflow (ad esempio `KYB_REGISTRY`, `AML`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`, `PHONE`, `EMAIL`) |
| `vendor_data` | string | Il tuo identificatore per l'azienda |
| `metadata` | object | JSON in formato libero che hai allegato alla creazione della sessione |
| `callback` | URL o null | URL di reindirizzamento facoltativo successivo alla verifica |
| `contact_details` | object o null | `{ email, email_lang, send_notification_emails, phone }` — presente quando il flusso include notifiche via email o telefono |
| `expected_details` | object o null | Payload dei dati attesi per l'azienda che hai passato alla creazione: `company_name`, `registry_country` (`XX` oppure `XX-YY` con lo stato per i registri a livello statale, ad esempio `US-CA`), `registration_number` |
| `reviews` | array | Ultime note del revisore sulla sessione |
| `created_at`, `expires_at` | timestamp ISO | — |

## `registry_checks[]`

Ogni elemento è un controllo sul registro delle imprese (in genere uno per sessione; più controlli nei workflow a grafo con KYB UBO aziendale ricorsivo).

```json theme={null}
{
  "status": "Approved",
  "node_id": "feature_kyb_registry",
  "data_resolved": true,
  "company": { ...see below... },
  "ownership_structure": { },
  "warnings": []
}
```

| Campo | Descrizione |
| - | - |
| `status` | Stato del ciclo di vita della funzionalità (`Approved`, `Declined`, `In Review`, `Not Finished`, `Resub Requested`) |
| `node_id` | Identificatore del nodo del grafo per questo controllo |
| `data_resolved` | `true` quando i dati del registro sono stati caricati completamente o quando l'utente ha inserito i dati manualmente |
| `company` | Payload completo del registro: vedi il **blocco `company`** più sotto |
| `ownership_structure` | La tabella di capitalizzazione che il registro ha confermato quando è stato consegnato il livello di assetto proprietario: `shareholders[]` e `beneficial_owners[]`, ciascuno con la stessa identità e quota di registro di `company.beneficial_owners[]` (`name`, `entity_type`, `roles`, `ownership_min_shares` / `ownership_max_shares`, ...) e il relativo `shareholding` canonico. `null` quando il registro non ha dimostrato alcun assetto proprietario. Per il record attuale consulta `company.beneficial_owners` e `company.ownership` |
| `warnings` | Avvisi strutturati / voci di log relativi a questo controllo sul registro. Vedi [avvisi di Verifica aziendale (KYB)](https://docs.didit.me/it/business-verification/warnings.md). |

### Blocco `company`

L'oggetto company annidato è la vista completa della persona giuridica ricavata dal registro (e, facoltativamente, modificata dall'utente):

```json theme={null}
{
  "uuid": "...",
  "node_id": "feature_kyb_registry",
  "status": "Approved",
  "registry_status": "active",
  "data_resolved": true,
  "company_name": "Acme Corporation Limited",
  "registration_number": "12345678",
  "country_code": "GBR",
  "company_type": "Private Limited",
  "incorporation_date": "2010-05-14",
  "registered_address": "1 Main Street, London EC1A 1AA, United Kingdom",
  "tax_number": "SAMPLE-TAX-12345",
  "risk_level": null,
  "verification_status": "verified",
  "is_from_registry": true,
  "fetch_status": "resolved",
  "alternative_names": "Acme Ltd",
  "nature_of_business": "Software publishing",
  "registered_capital": "100000 GBP",
  "website": "https://acme.example",
  "email": "alex.sample@example.com",
  "phone": "+15550101000",
  "legal_entity_identifier": "529900XXXXXXXXXXXXX",
  "location_of_registration": "London",
  "vat_number": "GB980780684",
  "vat_validation_status": "format_valid",
  "vat_validated_number": "GB980780684",
  "vat_validation_source": "format_rules",
  "vat_validated_name": null,
  "vat_validated_address": null,
  "vat_checked_at": "2026-04-16T10:10:00Z",
  "financial_summary": { },
  "officers": [ ... ],
  "beneficial_owners": [ ... ],
  "addresses": [
    {
      "type": "registered",
      "address": "1 Main Street, London EC1A 1AA, United Kingdom",
      "street": "1 Main Street",
      "city": "London",
      "postal_code": "EC1A 1AA",
      "region": null,
      "country_code": "GB",
      "description": null
    }
  ],
  "industries": [
    { "code": "58290", "description": "Other software publishing", "scheme": "UK SIC 2007", "is_primary": true }
  ],
  "accounts": { ... },
  "ownership": {
    "status": "delivered",
    "tier_requested": "ubo",
    "tier_delivered": "ubo",
    "unavailable_reason": null,
    "direct_ownership_complete": true,
    "unresolved": []
  },
  "registry_tier": "ubo",
  "registry_tier_delivered": "ubo",
  "registry_ownership_status": "delivered",
  "registry_monitoring": null,
  "registry_data": { },
  "user_provided_data": { },
  "confirmed_by_user_at": "2026-04-16T10:10:00Z",
  "last_console_edit_at": null,
  "is_editable": false
}
```

| Campo | Descrizione |
| - | - |
| `registry_status` | Stato riportato dal fornitore (`active`, `dissolved`, `struck_off`, `inactive`, ecc.). Vedi [stati](https://docs.didit.me/it/business-verification/statuses.md#stato-del-registro-dal-fornitore) |
| `is_from_registry` | `true` quando i dati provengono da un registro ufficiale; `false` per l'inserimento manuale |
| `fetch_status` | `pending`, `resolved` o `failed`: stato della ricerca nel registro |
| `verification_status` | `verified`, `failed` o `unknown` |
| `risk_level` | Valore facoltativo trasmesso dalla fonte del registro. Di solito è `null`: Didit non calcola un livello di rischio, quindi usa `warnings[]` e lo `status` della sessione per decidere |
| `registry_monitoring` | Il monitoraggio più recente del registro per l'azienda, oppure `null` se non esiste. Valorizzato solo quando il [monitoraggio del registro](https://docs.didit.me/it/business-verification/ownership.md#monitoraggio-di-azionisti-e-ubo) è disponibile. Campi: `uuid`, `status`, `unavailable_reason`, `enrolled_at`, `cancelled_at`, `last_bill_date`, `next_bill_date`, `last_event_at`, `events_count`, `watched_fields` |
| `is_editable` | `true` finché l'utente finale può ancora modificare i dati provenienti dal registro |
| `registry_data` | Dettaglio normalizzato del registro di Didit: l'esito della verifica dell'assetto proprietario (`ownership_error`, `section_errors`, `ubo_resolution`), le correzioni apportate con [update-data](https://docs.didit.me/it/sessions-api/update-data.md) e i dati del registro che non hanno un campo proprio. Non include mai il record proprio della fonte del registro. Le sue chiavi variano in base all'azienda e non è un contratto stabile: consulta invece i campi canonici |
| `user_provided_data` | I campi inseriti o modificati dall'utente finale (utile per confrontare in fase di audit i valori con quelli del registro) |
| `confirmed_by_user_at` | Data e ora in cui l'utente finale ha confermato o modificato i dati del registro |
| `vat_number` | Numero IVA così come inviato, quando raccolto |
| `vat_validation_status` | Esito della validazione del numero IVA, oppure del `tax_number` quando manca: `valid`, `invalid`, `format_valid`, `invalid_format`, `could_not_validate` o `not_applicable`. Vedi [validazione di IVA e identificativo fiscale](https://docs.didit.me/it/business-verification/company-data.md#validazione-del-numero-vat-e-dell’identificativo-fiscale) |
| `vat_validated_number` / `vat_validation_source` | Il numero controllato, come lo conosce la fonte, e la fonte che ha deciso lo stato (un registro ufficiale oppure `format_rules`) |
| `vat_validated_name` / `vat_validated_address` | Nome e indirizzo registrati presso la fonte, quando la fonte li rende disponibili |
| `vat_checked_at` | Data e ora del controllo; `null` quando non è stato eseguito alcun controllo |
| `officers[]` | Dirigenti con arricchimento KYC incorporato (vedi sotto) |
| `beneficial_owners[]` | Titolari effettivi (UBO) con arricchimento KYC incorporato (vedi sotto) |
| `addresses[]` | Ogni indirizzo indicato dal registro, nella struttura canonica dell'indirizzo riportata di seguito. `null` quando il registro non ne indica alcuno |
| `industries[]` | Le attività in cui il registro classifica l'azienda, nella struttura canonica del settore riportata di seguito. `null` quando il registro non ne indica alcuna |
| `accounts` | Date di deposito societario, quando riportate: `last_annual_return_date` e `last_agm_date`. Si riferiscono a depositi e assemblee, non ai bilanci |
| `ownership` | L'esito del livello di assetto proprietario (Azionisti / UBO), nella struttura canonica sotto |
| `registry_tier` / `registry_tier_delivered` / `registry_ownership_status` | Il livello richiesto, il livello consegnato (e fatturato) e l'esito dell'assetto proprietario. Gli stessi valori compaiono in `ownership` |

### Un formato per ogni paese e fonte di registro

Didit legge i registri delle imprese di molti paesi attraverso diverse fonti di registro.
Ogni fonte pubblica un proprio layout, ma il blocco `company` ha sempre la stessa struttura: le chiavi seguenti sono sempre presenti, con gli stessi tipi, indipendentemente dal paese e dalla fonte da cui proviene l'azienda.
Un dato che il registro non pubblica è `null`; non serve mai distinguere per paese o analizzare `registry_data`.
La stessa struttura viene restituita dalla [decisione](https://docs.didit.me/it/sessions-api/retrieve-session.md), dagli endpoint autonomi del [registro KYB](https://docs.didit.me/it/standalone-apis/kyb-registry-ubo.md) e dal flusso di verifica ospitato.

**Indirizzo** (ogni elemento di `addresses`)

| Campo | Descrizione |
| - | - |
| `type` | In minuscolo. `registered` per la sede legale; gli altri tipi così come li denomina il registro (ad esempio `postal`, `office`). `null` quando il registro non indica di che tipo di indirizzo si tratta |
| `address` | L'indirizzo completo su una sola riga. Sempre presente |
| `street`, `city`, `postal_code`, `region` | L'indirizzo suddiviso in parti, quando il registro le pubblica |
| `country_code` | ISO 3166-1 alpha-2 |
| `description` | L'etichetta del registro per l'indirizzo, quando ne fornisce una |

**Settore** (ogni elemento di `industries`)

| Campo | Descrizione |
| - | - |
| `code` | Codice di attività così come lo riporta il registro |
| `description` | Descrizione dell'attività, quando il registro ne pubblica una |
| `scheme` | Sistema di classificazione, con un unico nome per ciascun sistema indipendentemente dalla fonte che lo ha riportato (`UK SIC 2007`, `US SIC`, `NACE Rev. 2`, `NACE Rev. 2.1`, `NAF Rev. 2`, `CNAE`, `SBI`, `NOGA 2008`, `CAE Rev. 4`, `Canada SIC 1977`). Gli altri sistemi nazionali mantengono il nome del registro; `null` quando il registro non lo indica |
| `is_primary` | `true` per indicare l'attività principale. Esattamente una voce è primaria |

Quando il registro indica le attività ma non una descrizione dell'attività, `nature_of_business` viene compilato con le etichette delle attività.
I recapiti e i nomi alternativi vengono compilati quando disponibili, mentre le modifiche esplicite apportate dall'utente o dal revisore hanno sempre la precedenza.

**Assetto proprietario** (`ownership`)

| Campo | Descrizione |
| - | - |
| `status` | `delivered`; `not_held` quando il registro dell'assetto proprietario ha risposto e non elenca affatto questa azienda, quindi non esiste alcun record di assetto proprietario da restituire; `unavailable` quando i dati non sono stati restituiti per qualsiasi altro motivo (un record che non indica alcun titolare, una sezione sull'assetto proprietario non restituita oppure un fornitore che non ha potuto essere interrogato); `pending` mentre il registro sta ancora recuperando la sezione sull'assetto proprietario; `not_requested` nel livello Basic |
| `tier_requested` / `tier_delivered` | `basic`, `shareholders` o `ubo`. Una richiesta UBO a cui si risponde con i soli azionisti diretti viene erogata, e fatturata, come `shareholders` |
| `unavailable_reason` | Motivo per cui un livello di assetto proprietario richiesto non è stato erogato: `no_owners_on_record`, `no_natural_person_owner`, `ownership_section_unavailable`, `company_not_found`, `ambiguous_company_match`, `missing_registration_number`, `entity_type_not_covered`, `provider_unavailable` o `other`. `null` quando l'assetto proprietario è stato erogato |
| `direct_ownership_complete` | `true` quando le quote dichiarate degli azionisti diretti ammontano complessivamente al 100% (con uno scostamento massimo di un punto percentuale dovuto all'arrotondamento), `false` quando non raggiungono tale valore, `null` quando l'assetto proprietario non è stato erogato o una quota non è dichiarata |
| `unresolved[]` | Parti della catena dell'assetto proprietario che il registro non è riuscito a risolvere, come `{ reason, section }` (ad esempio `no_group_structure_on_record` per `group_structure`: i titolari diretti sono noti, ma il gruppo societario sovraordinato non risulta nel registro) |

**Dettaglio del registro** (`registry_data`)

Dettaglio di Didit sul controllo del registro, mai il record della fonte del registro.
Ogni chiave è facoltativa e presente solo quando l'azienda ha un valore per quel campo, e possono essere aggiunte nuove chiavi: per ciò che coprono, consulta i campi canonici sopra.

| Campo | Descrizione |
| - | - |
| Dati del registro (`legal_address`, `registered_address`, `registration_date`, `dissolution_date`, `registry_status`, `verification_status`, `company_type` e gli altri campi che [update-data](https://docs.didit.me/it/sessions-api/update-data.md) accetta) | Stringhe. Le correzioni apportate con update-data e i dati che il registro riporta e che non hanno un campo proprio (`registration_date`, `dissolution_date`) |
| `ownership_error` | Motivo per cui un livello di assetto proprietario richiesto non è stato erogato, con gli stessi codici di `ownership.unavailable_reason` (`no_owners_on_record`, `ownership_section_unavailable`, `company_not_found`, `provider_unavailable`, `other`, ...) |
| `section_errors` | Sezioni che il registro non ha restituito, indicizzate per sezione (`officers`, `shareholders`, `group_structure`), ciascuna `{ status_code }` |
| `ubo_resolution` | Come il livello UBO ha percorso la catena: `parent_chain[]` e `subsidiaries[]` come `{ name, country_code, registration_number }`, e `unresolved[]` come `{ reason, section }` |
| `lite_enrichment` | Campi vuoti del livello Lite compilati da un'altra fonte di registro del paese: `{ fields[], people_added }` |
| `registry_metadata`, `registry_sources[]`, `previous_names[]`, `parent_companies[]`, `documents_available` | Solo per i record di registro meno recenti: i campi propri del registro, i registri ufficiali consultati (`{ name, source_type }`, sono indicati solo i registri ufficiali), i nomi precedenti, i nomi delle società capogruppo e il numero di depositi disponibili |

### Struttura dell'elemento relativo a un dirigente (all'interno di `company.officers`)

```json theme={null}
{
  "uuid": "...",
  "name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": null,
  "date_of_birth_year": 1983,
  "date_of_birth_month": 2,
  "address": "1 Example Street, London",
  "appointment_date": "2024-07-01",
  "termination_date": null,
  "designation": "Director",
  "role": "director",
  "nationality": "USA",
  "is_active": true,
  "kyc_status": "Approved",
  "kyc_session_url": "https://verify.didit.me/..."
}
```

`date_of_birth` viene compilato solo quando il registro fornisce una data completa.
Se il registro riporta solo l'anno o il mese e l'anno, usa `date_of_birth_year` e `date_of_birth_month`; il giorno mancante non viene mai dedotto.
Nomi, dati di nascita, indirizzo e date di nomina restano disponibili sia nell'elenco dei dirigenti sia nell'elenco delle persone chiave del registro.

### Struttura dell'elemento titolare effettivo (all'interno di `company.beneficial_owners`)

```json theme={null}
{
  "uuid": "...",
  "name": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "entity_type": "person",
  "date_of_birth": null,
  "country_of_birth": null,
  "email": null,
  "company_name": null,
  "registration_number": null,
  "nationality": null,
  "designation": null,
  "appointment_date": null,
  "voting_min_shares": null,
  "voting_max_shares": null,
  "roles": ["ubo"],
  "ownership_min_shares": "40",
  "ownership_max_shares": "40",
  "is_active": true,
  "kyc_status": "Pending",
  "kyc_session_url": "https://verify.didit.me/...",
  "effective_ownership_percent": 40.0,
  "shareholding": {
    "share_class": "Ordinary",
    "number_of_shares": 40,
    "currency": "GBP",
    "nominal_value": 1,
    "total_value": null,
    "percentage": 40
  }
}
```

`kyc_status` usa una proiezione sicura per l'uso B2C: `Approved`, `Declined` o `Pending` (gli stati completi della sessione si riducono a `Pending` finché il KYC non è completato).

`shareholding` indica ciò che il titolare detiene, nella stessa forma per ogni paese e fonte di registro: `share_class`, `number_of_shares`, `currency`, `nominal_value`, `total_value` e `percentage` (la quota esatta, a quattro cifre decimali).
È `null` quando il registro non indica alcuna partecipazione.
Una fascia, come il 25-50% di un PSC del Regno Unito, non è una quota: `percentage` è `null` e la fascia resta in `ownership_min_shares` / `ownership_max_shares`.
Azionisti e UBO sono entrambi elencati in `beneficial_owners`; `roles` li distingue.

## `key_people_checks[]`

Questo è il **controllo aggregato** su tutti i dirigenti e gli UBO della sessione. Espone due gruppi, così la console può mostrare affiancati i dati "estratti dal registro" e quelli "inseriti dall'azienda", più un riepilogo di alto livello del KYC sugli UBO.

```json theme={null}
{
  "status": "Approved",
  "node_id": "feature_kyb_key_people",
  "registry": {
    "officers": [ ...registry-derived officers... ],
    "beneficial_owners": [ ...registry-derived UBOs... ]
  },
  "submitted": {
    "parties": [ ...user-submitted key-people records... ]
  },
  "ubo_kyc_summary": {
    "total": 2,
    "approved": 1,
    "flagged": 0,
    "pending": 1
  },
  "warnings": []
}
```

* **`registry.officers` / `registry.beneficial_owners`**: soggetti estratti dal controllo sul registro.
* **`submitted.parties`**: soggetti che l'amministratore aziendale ha aggiunto esplicitamente durante il flusso Key People (record con `source = "USER"`).

### `registry.officers[]` / `registry.beneficial_owners[]`

I dati del registro corrispondono a `company.officers` / `company.beneficial_owners` descritti sopra.
Key People include inoltre lo stato AML e il collegamento dettagliato alla verifica, come `kyc_session_id` e i campi del workflow di verifica.
Gli elenchi dell'azienda mantengono il loro stato KYC semplificato e l'URL di verifica già esistenti.

### `submitted.parties[]`

I soggetti inseriti dall'utente includono il collegamento alla loro sessione KYC o KYB figlia:

```json theme={null}
{
  "uuid": "...",
  "entity_type": "person",
  "name": "Alice Chen",
  "first_name": "John",
  "last_name": "Doe",
  "email": "alex.sample@example.com",
  "role": "ubo",
  "ownership_percent": 35.0,
  "nationality": "USA",
  "position": "CEO",
  "date_of_birth": "1990-01-01",
  "phone_number": "+34612345678",
  "source": "USER",
  "requires_verification": true,
  "is_skipped": false,
  "kyc_session_id": "sess-xyz...",
  "kyc_session_status": "Not Started",
  "kyc_session_url": "https://verify.didit.me/...",
  "kyc_session_deleted": false,
  "custom_fields": { }
}
```

I soggetti aziendali (`entity_type: "company"`) includono anche `company_name`, `registration_number` e `kyb_sub_session_id` / `kyb_sub_session_status` / `kyb_sub_session_deleted` quando il KYB annidato è abilitato per gli UBO aziendali.

`kyc_session_deleted` (e il suo equivalente aziendale `kyb_sub_session_deleted`) è `true` quando la sessione figlia del soggetto è stata eliminata. Una sessione figlia eliminata conserva lo stato che aveva al momento dell'eliminazione e non può mai concludersi: leggi quindi questo flag invece dello stato. L'URL `*_session_url` corrispondente viene restituito come `null` perché il link non è più risolvibile, e il controllo Key People passa a `In Review` invece di restare in attesa all'infinito. L'eliminazione di una sessione figlia non viene mai considerata un esito positivo. Per esentare il soggetto usa [`PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`](https://docs.didit.me/it/sessions-api/update-data#escludere-una-parte-della-sezione-key-people), in modo che il KYB possa concludersi.

### `ubo_kyc_summary`

Avanzamento aggregato del KYC sugli UBO, utile per una singola scheda della dashboard:

| Campo | Significato |
| - | - |
| `total` | Numero di UBO attivi che hanno una sessione KYC collegata |
| `approved` | Gli UBO le cui sessioni KYC sono `Approved` |
| `flagged` | Gli UBO le cui sessioni KYC sono `Declined` o `In Review` |
| `pending` | Tutti gli altri (non ancora conclusi) |

Restituisce `null` quando nessun UBO ha sessioni KYC collegate.

## `document_verifications[]`

Documenti raggruppati per nodo:

```json theme={null}
{
  "status": "Approved",
  "node_id": "feature_kyb_documents",
  "items": [
    {
      "uuid": "...",
      "document_type": "LEGAL_PRESENCE",
      "document_subtype": "CERTIFICATE_OF_INCORPORATION",
      "document_group": "LEGAL_PRESENCE",
      "status": "Approved",
      "file_url": "https://didit-storage.s3...",
      "document_metadata": {
        "file_size": 246810,
        "content_type": "application/pdf",
        "creation_date": "2024-05-15",
        "modified_date": "2024-05-15",
        "overlay_manipulation": null
      },
      "ocr_data": {
        "company_name": "Acme Corporation Limited",
        "registration_number": "12345678",
        "incorporation_date": "2010-05-14"
      }
    }
  ],
  "groups": {
    "LEGAL_PRESENCE": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 },
    "OWNERSHIP_STRUCTURE": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 }
  },
  "required_groups": ["LEGAL_PRESENCE", "OWNERSHIP_STRUCTURE"],
  "warnings": []
}
```

| Campo | Descrizione |
| - | - |
| `items[]` | Singole righe dei documenti: ognuna ha il proprio `status`, `document_type` e `document_group` (il gruppo), `document_subtype`, `file_url` (firmato), `document_metadata` ed estratto OCR |
| `groups` | Contatori di avanzamento per gruppo, indicizzati in base al valore del gruppo (`LEGAL_PRESENCE`, `COMPANY_DETAILS`, `OWNERSHIP_STRUCTURE`, `REPRESENTATIVES_AUTHORIZATION`, più `OTHER` per i documenti non classificati). Ogni gruppo contiene `total`, `approved`, `pending`, `declined`, `in_review`, `other` e `missing`. Vedi i [gruppi di documenti KYB](https://docs.didit.me/it/business-verification/documents.md#gruppi-di-documenti) |
| `required_groups` | Gruppi che il tuo workflow ha contrassegnato come obbligatori: l'approvazione della sessione dipende dal soddisfacimento di tutti |

### Metadati dei documenti societari

Per i documenti societari in PDF, `items[].document_metadata.overlay_manipulation` può includere evidenze forensi di una sospetta modifica del testo sovrapposto. Quando presente, include:

| Campo | Descrizione |
| - | - |
| `analysis_incomplete` | Presente e impostato su `true` solo quando il file non è stato verificato per intero. Le parti verificate mantengono, ove possibile, i relativi risultati, e il documento genera `KYB_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`. |
| `detected` | Se è stata rilevata una manipolazione del testo sovrapposto |
| `analyzed` | Se il PDF è stato analizzato |
| `signals` | Segnali forensi attivati, come `duplicate_font_subset` o `glyph_fragmentation` |
| `manipulated_regions` | Rettangoli in coordinate di pagina del PDF attorno al testo sospettato di essere modificato: `page`, `x`, `y`, `width`, `height`, `page_width`, `page_height` |

Il campo è `null` quando non è stata trovata alcuna evidenza di sovrapposizione, quando il documento non è un PDF, o quando il PDF non può essere analizzato.

## `aml_screenings[]`

Screening AML a livello aziendale e, quando il workflow li collega, a livello di persona.

```json theme={null}
{
  "node_id": "feature_aml",
  "status": "Approved",
  "total_hits": 0,
  "score": 0,
  "entity_type": "COMPANY",
  "screened_data": {
    "company_name": "Acme Corporation Limited",
    "country_code": "GBR"
  },
  "is_ongoing_monitoring_enabled": true,
  "next_ongoing_monitoring_bill_date": "2027-04-16",
  "last_ongoing_screening_at": "2026-09-12T04:03:11Z",
  "last_ongoing_screening_datasets_updated_at": null,
  "hits": [],
  "warnings": []
}
```

Quando `total_hits > 0`, ogni riscontro include il punteggio di corrispondenza, il punteggio di rischio, le fonti delle watchlist e un `review_status` per singolo riscontro, che puoi aggiornare tramite l'endpoint di aggiornamento dello stato dei riscontri AML. Vedi il [report Screening AML](https://docs.didit.me/it/core-technology/aml-screening/report-aml-screening.md) per la struttura dei riscontri.

## Array di funzionalità condivise

`phone_verifications`, `email_verifications`, `questionnaire_responses` e `ip_analyses` usano gli stessi schemi per elemento delle sessioni utente (KYC). Sono `null` quando il workflow non le include. Vedi la [risposta KYC](https://docs.didit.me/it/sessions-api/retrieve-session.md) per gli schemi degli elementi.

`signatures` è presente quando il workflow include un passaggio di [Firma elettronica](https://docs.didit.me/it/core-technology/electronic-signature/overview.md). In una sessione aziendale c'è un elemento per ogni persona chiave che firma per conto dell'azienda, con `signer.capacity: "company"`, il nome dell'azienda e i ruoli della persona chiave. Vedi il [report della Firma elettronica](https://docs.didit.me/it/core-technology/electronic-signature/report-electronic-signature.md).

## Gruppi di avvisi per funzionalità

Gli avvisi di Verifica aziendale (KYB) sono raggruppati in base alla funzionalità che li ha generati:

* `KYB_REGISTRY` per disponibilità del registro, assetto proprietario, attività aziendale e problemi di restrizioni per paese.
* `KYB_DOCUMENTS` per estrazione dei documenti aziendali, controlli incrociati, metadati, manipolazione, sottotipo, età e limiti di tentativi.
* `AML` per corrispondenze nello screening AML aziendale o per dati di screening mancanti.
* `KYB_KEY_PEOPLE` per problemi a livello di persona legati ad amministratori, dirigenti, UBO o rappresentanti.
* `PHONE` per rischio del numero di telefono, duplicazioni, blocklist e tentativi di inserimento del codice di verifica.
* `EMAIL` per rischio dell'email, recapitabilità, duplicazioni, blocklist e tentativi di inserimento del codice di verifica.
* `QUESTIONNAIRE` per regole di stato personalizzate basate sulle risposte al questionario.
* `LOCATION` per Analisi dispositivo e IP, rete privata, blocklist IP, blocklist dei dispositivi e duplicazioni di dispositivo/IP.
* `SIGNATURE` per rifiuti della Firma elettronica, conferme del codice non riuscite, mancate corrispondenze del nome del firmatario, firmatari non verificati, documenti modificati e dati dei campi mancanti. Vedi gli [avvisi della Firma elettronica](https://docs.didit.me/it/core-technology/electronic-signature/warnings-electronic-signature.md).

Vedi gli [avvisi di Verifica aziendale (KYB)](https://docs.didit.me/it/business-verification/warnings.md) per l'elenco completo dei codici di avviso.

## Filtraggio dei campi guidato dal workflow

I workflow possono limitare i campi annidati che compaiono in ciascun elemento delle funzionalità tramite `response_attributes`. I campi sempre inclusi, in ogni caso, sono `status`, `warnings` e `node_id`. Tutti gli altri campi vengono impostati a null quando non sono nella lista degli ammessi: la chiave resta nella risposta per mantenere stabile lo schema.

## Prossimi passi

> [card] [Stati](https://docs.didit.me/it/business-verification/statuses.md)
>
> Il significato di ciascun valore di stato.

> [card] [Valutazione del rischio](https://docs.didit.me/it/business-verification/risk-assessment.md)
>
> Cosa determina l'esito di una verifica KYB.

> [card] [Report AML](https://docs.didit.me/it/core-technology/aml-screening/report-aml-screening.md)
>
> Riferimento completo del payload dei riscontri AML.

> [card] [Persone chiave](https://docs.didit.me/it/business-verification/key-people.md)
>
> Come le parti confluiscono dal registro o dall'invio dell'utente nei gruppi `registry` / `submitted`.

> [card] [Documenti](https://docs.didit.me/it/business-verification/documents.md)
>
> Gruppi di documenti, OCR e riferimenti incrociati.

> [card] [Recupera sessione](https://docs.didit.me/it/sessions-api/retrieve-session.md)
>
> Riferimento completo dell'endpoint, con esempi di risposta.


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