API registro KYB: ricerca e selezione aziende

Endpoint e fatturazione

Le ricerche autonome riuscite che usano una fonte di dati aziendali a pagamento costano $0.50 per richiesta, indipendentemente dal numero di candidati. I risultati vuoti, le ricerche non riuscite e i risultati forniti solo da altre fonti non vengono addebitati. Il recupero successivo del profilo viene fatturato separatamente. Il recupero è venduto in tre livelli di dati, ciascuno con un proprio endpoint, con prezzi diversi per paese (prezzi per paese):

Endpoint	Cosa ottieni	Prezzo
`POST /v3/kyb/search/`	Aziende candidate: nome, numero di registrazione, stato, tipo	$0.50 quando vengono restituiti risultati da fonti a pagamento
`POST /v3/kyb/select/`	Lite: il profilo aziendale (identificativi, stato, forma giuridica, data di costituzione, indirizzo registrato, attività, recapiti) e gli esponenti aziendali	Prezzo Lite: $2.00-$3.00 a seconda del paese
`POST /v3/kyb/shareholders/`	Lite più gli azionisti diretti con le rispettive fasce di partecipazione	Prezzo Shareholders: $5.00-$22.00 a seconda del paese
`POST /v3/kyb/ubo/`	Shareholders più i titolari effettivi individuati lungo la catena di partecipazione	Prezzo UBO: $9.00-$96.00 a seconda del paese

select è il livello Lite: è ciò che un workflow KYB ospitato addebita per un controllo nel registro a livello Lite, e mantiene il contratto che ha sempre avuto. Per Europa si intendono lo Spazio economico europeo (EEA), il Regno Unito e la Svizzera. Una ricerca Shareholders o UBO interroga la fonte sull’assetto proprietario che serve il livello richiesto. Quando tale fonte risponde che non dispone di informazioni sull’azienda, la ricerca interroga anche le altre fonti registrali del paese, così un’azienda che la fonte sull’assetto proprietario non elenca viene comunque proposta come candidata invece di finire in inserimento manuale. I candidati trovati in questo modo mantengono il livello richiesto: al recupero viene ricontrollata la fonte sull’assetto proprietario e, se questa continua a non disporre di informazioni sull’azienda, viene consegnato e fatturato il profilo Lite, con registry_ownership_status: "not_held".

Paghi il livello consegnato. Ogni risposta contiene registry_tier_requested e registry_tier_delivered. Quando i registri del paese non hanno dati sull’assetto proprietario, oppure il registro non ha una registrazione di assetto proprietario per l’azienda selezionata, una richiesta di assetto proprietario viene consegnata e fatturata al livello più alto disponibile (di solito Lite), e registry_ownership_status ne indica il motivo. Una richiesta UBO il cui report elaborato non indica alcuna persona fisica come titolare effettivo viene consegnata e fatturata come Shareholders.

Versionamento. Gli endpoint Shareholders e UBO esistono solo su /v3/. La commissione per la ricerca autonoma si applica anche a /v2/kyb/search/; il recupero del profilo viene fatturato separatamente.

Stato dell’assetto proprietario

registry_ownership_status indica cosa è successo alla parte relativa all’assetto proprietario di una richiesta Shareholders o UBO:

Valore	Significato
`not_requested`	La chiamata era un recupero Lite, quindi non è stato richiesto alcun assetto proprietario.
`delivered`	Il registro ha fornito i dati sull’assetto proprietario, e il livello in `registry_tier_delivered` è quello che paghi.
`not_held`	Il registro dell’assetto proprietario ha risposto ma non elenca questa azienda, quindi non dispone di alcun record di assetto da fornire: l’azienda è stata trovata da un’altra fonte del registro del paese. Il profilo Lite viene consegnato e fatturato al suo posto, con `registry_data.ownership_error: "company_not_found"`.
`unavailable`	I dati sull’assetto proprietario non sono stati forniti per qualsiasi altro motivo: il record del registro non indica alcun titolare, oppure il registro non ha restituito affatto la sezione sull’assetto proprietario, oppure non è stato possibile interrogarlo. `registry_data.ownership_error` indica quale. Il profilo Lite viene consegnato e fatturato al suo posto.
`pending`	La sezione sull’assetto proprietario non è ancora stata recuperata dal registro. Non viene addebitato nulla e `registry_tier_delivered` è `null` finché non avviene il recupero.

not_held e unavailable vengono entrambi consegnati e fatturati come Lite, ma non indicano lo stesso esito: not_held significa che la fonte sull’assetto proprietario non copre l’azienda, cioè una lacuna di copertura, mentre unavailable significa che i dati non sono stati forniti, a causa di un’interruzione o di una sezione lasciata vuota dal registro. registry_data.ownership_error indica il motivo. Le selezioni che in precedenza riportavano unavailable perché il registro dell’assetto proprietario non elencava l’azienda ora riportano not_held; se implementi una diramazione in base allo stato, tratta entrambi i casi come la stessa consegna Lite. Due dei suoi valori hanno significati diversi e non devono essere letti come lo stesso esito:

`ownership_error`	Significato
`no_owners_on_record`	Il registro ha risposto per la sezione sull’assetto proprietario e non indica alcun titolare. Il registro non ha nei propri archivi alcun prospetto dell’assetto proprietario dell’azienda.
`ownership_section_unavailable`	Il registro non ha restituito la sezione sull’assetto proprietario, quindi per essa non è stato consegnato nulla. L’elenco manca, non è vuoto: non dice nulla su chi possiede l’azienda.

Una sezione che il registro non ha restituito viene registrata anche in modo strutturato, in registry_data.section_errors, indicizzata per sezione (officers, shareholders, group_structure) con lo stato con cui il registro ha risposto:

{
  "section_errors": {
    "shareholders": {
      "status_code": 404
    }
  }
}

section_errors descrive la risposta che stai ricevendo, non la storia che ha portato ad essa. Una sezione non restituita alla prima richiesta e fornita in un passaggio successivo (vedi il recupero asincrono qui sotto) perde la sua voce, quindi registry_ownership_status, ownership_error e section_errors concordano sempre: una sezione delivered non ha mai una voce, e no_owners_on_record non è mai accompagnato da una voce per shareholders. Una sezione non viene inoltre mai consegnata in parte: se il registro fornisce la prima pagina di un elenco e poi non riesce a fornire una pagina successiva, il recupero non si considera completato in quel tentativo. Un recupero pending viene ritentato al passaggio successivo, mentre una nuova richiesta riceve l’errore di indisponibilità del registro. Quindi un elenco officers o degli azionisti consegnato è sempre l’elenco completo che il registro possiede. Tratta una sezione elencata in section_errors come dato mai consegnato, mai come risultato vuoto: un elenco officers o degli azionisti vuoto accanto a una voce section_errors per la stessa sezione non dice nulla sull’azienda.

Assetto proprietario recuperato in modo asincrono

Alcuni registri vengono interrogati su richiesta: la prima richiesta per un’azienda su cui la fonte non è mai stata interrogata non restituisce alcuna sezione sull’assetto proprietario mentre viene recuperata, e i dati arrivano entro un paio di minuti. Segnalarlo come “nessun assetto proprietario registrato” sottostimerebbe un’azienda che in realtà ha degli azionisti, quindi in questo caso la richiesta restituisce pending. Mentre un recupero è pending, anche fetch_status è pending e lo stato della risposta è 202 Accepted. Didit ritenta la sezione autonomamente e completa il recupero senza ulteriori chiamate da parte tua:

non appena arrivano i dati sull’assetto proprietario, gli azionisti e i titolari effettivi compaiono nella verifica salvata, registry_tier_delivered diventa il livello che è stato fornito e l’utilizzo viene addebitato a quel livello;
se la sezione è ancora vuota alla chiusura della finestra di nuovo tentativo, lo stato diventa unavailable e la richiesta viene consegnata e fatturata come Lite.

Conserva il request_id e interroga GET /v3/session/{request_id}/decision/ finché registry_checks[0].company.fetch_status non diventa resolved. Non ripetere la richiesta di recupero mentre è pending: ogni nuova POST è una richiesta separata, fatturabile separatamente. Usa POST /v3/kyb/search/ per trovare le aziende candidate. La ricerca non crea una verifica salvata. L’input tier della ricerca sceglie la catena su cui cerca: vedi livello di ricerca. Le ricerche nei registri possono richiedere circa 90 secondi. Invia webhook_url se vuoi che Didit restituisca subito la risposta e invii una notifica al tuo URL quando i candidati sono pronti. La callback di ricerca non è firmata di proposito, quindi per questa notifica leggera non devi configurare un segreto condiviso. Usa POST /v3/kyb/select/, POST /v3/kyb/shareholders/ o POST /v3/kyb/ubo/ con il kyb_response_id restituito per recuperare il profilo al livello che ti serve. Il recupero è fatturabile e salva il risultato come Manual Check nella Business Console.

Flusso tipico

Cerca per nome dell’azienda, numero di registrazione e paese, sul tier che intendi acquistare (basic è la catena Lite predefinita; shareholders e ubo cercano nella catena di quel livello).
Se search_resolved=false, attendi la callback facoltativa webhook_url invece di interrogare il servizio.
Mostra i candidati restituiti al tuo operatore o cliente.
Recupera il kyb_response_id corrispondente al livello che ti serve (select per Lite, shareholders o ubo).
Conserva il request_id restituito e usalo per recuperare il risultato salvato della verifica aziendale.

Callback di ricerca

Quando il provider comunica a Didit che la ricerca è completata, Didit invia una singola richiesta POST al tuo webhook_url:

{
  "event_id": "7f5a1c93-6a44-4f0e-9f2b-3d8a1c6f2e91",
  "event_type": "kyb.registry_search.resolved",
  "request_id": "b5ef9df5-bd9e-4d61-bbe5-5eb7a8fb6f85",
  "vendor_data": "business-123",
  "metadata": {
    "source": "onboarding"
  },
  "search_status": "resolved",
  "search_resolved": true,
  "kyb_registry": {
    "companies": [
      {
        "kyb_response_id": "kyb_resp_123",
        "name": "TESCO PLC",
        "registration_number": "00445790",
        "status": "active",
        "type": "Public Limited Company",
        "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA",
        "risk_level": null,
        "fetch_status": "pending"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "per_page": 25
    },
    "search_status": "resolved",
    "search_resolved": true
  },
  "timestamp": 1767225600,
  "created_at": 1767225600
}

Considera il callback come una notifica di consegna. Usa il kyb_response_id restituito con POST /v3/kyb/select/, POST /v3/kyb/shareholders/ o POST /v3/kyb/ubo/ per eseguire il recupero del profilo nel registro, che è a pagamento.

Ultima modifica il 7 novembre 2026

​Endpoint e fatturazione

​Stato dell’assetto proprietario

​Assetto proprietario recuperato in modo asincrono

​Flusso tipico

​Callback di ricerca

Endpoint e fatturazione

Stato dell’assetto proprietario

Assetto proprietario recuperato in modo asincrono

Flusso tipico

Callback di ricerca