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

Questa pagina documenta il payload completo restituito da GET /v3/session/{id}/decision/ 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

{
  "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)
`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).

{
  "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).

Blocco `company`

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

{
  "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
`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 è 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 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
`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, dagli endpoint autonomi del registro KYB 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 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`)

{
  "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`)

{
  "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.

{
  "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:

{
  "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}/, 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:

{
  "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
`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.

{
  "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 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 per gli schemi degli elementi. signatures è presente quando il workflow include un passaggio di Firma elettronica. 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.

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.

Vedi gli avvisi di Verifica aziendale (KYB) 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

Stati

Il significato di ciascun valore di stato.

Valutazione del rischio

Cosa determina l’esito di una verifica KYB.

Report AML

Riferimento completo del payload dei riscontri AML.

Persone chiave

Come le parti confluiscono dal registro o dall’invio dell’utente nei gruppi registry / submitted.

Documenti

Gruppi di documenti, OCR e riferimenti incrociati.

Recupera sessione

Riferimento completo dell’endpoint, con esempi di risposta.

Primi passi

Funzionalità

Profili aziendali

Riferimento

Console

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

Struttura di primo livello

Campi di primo livello comuni

`registry_checks[]`

Blocco `company`

Un formato per ogni paese e fonte di registro

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

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

`key_people_checks[]`

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

`submitted.parties[]`

`ubo_kyc_summary`

`document_verifications[]`

Metadati dei documenti societari

`aml_screenings[]`

Array di funzionalità condivise

Gruppi di avvisi per funzionalità

Filtraggio dei campi guidato dal workflow

Prossimi passi

Stati

Valutazione del rischio

Report AML

Persone chiave

Documenti

Recupera sessione

​Struttura di primo livello

​Campi di primo livello comuni

​registry_checks[]

​Blocco company

​Un formato per ogni paese e fonte di registro

​Struttura dell’elemento relativo a un dirigente (all’interno di company.officers)

​Struttura dell’elemento titolare effettivo (all’interno di company.beneficial_owners)

​key_people_checks[]

​registry.officers[] / registry.beneficial_owners[]

​submitted.parties[]

​ubo_kyc_summary

​document_verifications[]

​Metadati dei documenti societari

​aml_screenings[]

​Array di funzionalità condivise

​Gruppi di avvisi per funzionalità

​Filtraggio dei campi guidato dal workflow

​Prossimi passi

Stati

Valutazione del rischio

Report AML

Persone chiave

Documenti

Recupera sessione

Struttura di primo livello

Campi di primo livello comuni

`registry_checks[]`

Blocco `company`

Un formato per ogni paese e fonte di registro

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

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

`key_people_checks[]`

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

`submitted.parties[]`

`ubo_kyc_summary`

`document_verifications[]`

Metadati dei documenti societari

`aml_screenings[]`

Array di funzionalità condivise

Gruppi di avvisi per funzionalità

Filtraggio dei campi guidato dal workflow

Prossimi passi