Vai al contenuto principale
POST
curl
Usa prima questo endpoint per trovare i candidati corrispondenti nel registro delle imprese. La ricerca non crea un Manual Check salvato. Le ricerche standalone 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 è fatturato separatamente. Per una ricerca che può usare una fonte a pagamento, Didit verifica e riserva il prezzo di ricerca applicabile prima di contattare il registro. Un saldo insufficiente restituisce 403 con code: "insufficient_credits". La fatturazione contrattuale segue la tariffa di ricerca concordata; una tariffa contrattuale non configurata viene rifiutata prima della ricerca. Le ricerche in sandbox sono gratuite. Ogni ricerca riuscita ripetuta è una nuova richiesta fatturabile; la consegna del callback non aggiunge un ulteriore addebito di ricerca. Se invii webhook_url, Didit può restituire subito una risposta mentre il fornitore risolve la ricerca, e poi inviare i candidati al tuo URL di callback quando sono pronti. Il callback non è firmato per scelta progettuale, quindi non è necessario configurare un segreto del webhook per questa notifica di ricerca. Vedi l’esempio di payload del callback di ricerca. Dopo aver scelto il kyb_response_id corretto, chiama POST /v3/kyb/select/ (Lite), POST /v3/kyb/shareholders/ oppure POST /v3/kyb/ubo/ per recuperare il profilo del registro fatturabile al livello che ti serve.
Ogni fetch_status del candidato è pending al momento della ricerca e resta pending finché non selezioni quel candidato: la ricerca si limita a elencare i candidati, mentre la selezione è ciò che recupera il profilo completo. Non fare polling sulla ricerca in attesa che si risolva.kyb_response_id è un identificatore opaco ed effimero, limitato a una singola richiesta di ricerca: restituiscilo esattamente come lo hai ricevuto, non analizzarlo né derivare nulla dal suo contenuto, e aspettati che ripetere la stessa ricerca restituisca nuovi id. Seleziona il candidato tempestivamente dopo la ricerca e usa registration_number quando ti serve un identificatore stabile dell’azienda stessa.

Livello di ricerca

tier seleziona il livello di registro la cui catena di fornitori esegue la ricerca: basic (predefinito, la catena Lite), shareholders oppure ubo. L’elenco dei candidati proviene dalla catena di quel livello, che non sempre è la fonte letta dalla ricerca Lite. Per questo una ricerca Lite vuota non dimostra che il registro non contenga l’azienda: ripeti la ricerca al livello che ti serve. Quando il paese non offre il livello indicato, la ricerca viene eseguita sul livello più alto che il paese offre fino a quello richiesto. Un paese senza alcun dato di registro non è disponibile per i controlli sul registro; prosegui con l’inserimento manuale dell’azienda. Esegui la ricerca al livello che intendi acquistare, poi recupera il candidato dall’endpoint che lo vende:

search_type

search_type accetta solo contains, che è anche il valore predefinito. Le fonti del registro delle imprese alla base della ricerca cercano il nome dell’azienda verificando se contiene il termine cercato, quindi start_with e fuzzy vengono rifiutati con 400 ("start_with" is not a valid choice) invece di essere trattati silenziosamente come contains. Invia registration_number per una corrispondenza esatta dell’azienda.

Ricerca ospitata e standalone

POST /v1/kyb/search/ è la ricerca eseguita da un flusso di verifica ospitato: è autenticata dalla sessione di verifica, rifiuta le richieste con una chiave API restituendo 403 e non accetta tier, perché la configurazione del registro KYB del workflow sceglie la catena. L’API standalone chiama POST /v2/kyb/search/ o POST /v3/kyb/search/ con la tua x-api-key. L’input tier e gli endpoint di selezione per livello sono il modo in cui un’integrazione standalone raggiunge gli stessi candidati, al livello di cui ha bisogno.

Gestire le interruzioni del registro

Se il fornitore del registro non è temporaneamente disponibile, l’endpoint restituisce 502 con un codice stabile leggibile dalla macchina:
Quando ricevi questo codice, lascia che l’utente continui con l’inserimento manuale dell’azienda oppure chiedigli di riprovare più tardi. Tieni separati gli errori di validazione: un input di ricerca non valido restituisce 400 e non usa questo codice di interruzione.

Gestire i paesi non supportati e i limiti di ricerca

Altri due codici stabili indicano di smettere di riprovare e proseguire con l’inserimento manuale dell’azienda: Nel flusso ospitato, ogni passaggio di registro consente 3 ricerche su una fonte di dati aziendali a pagamento. Dopo la terza, al richiedente viene offerto l’inserimento manuale. Selezionare un candidato che è una registrazione di marchio anziché un’azienda restituisce 400 con code: "kyb_registry_entry_not_a_company". Scegli invece un’azienda tra i risultati della ricerca.

Autorizzazioni

x-api-key
string
header
obbligatorio

La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys.

Corpo

application/json
country_code
string
obbligatorio

Codice ISO 3166-1 alpha-2 del paese nel cui registro delle imprese effettuare la ricerca. Ad esempio, GB. Laddove i registri delle imprese operano a livello statale o provinciale, aggiungi il codice di suddivisione ISO 3166-2 come XX-YY: US-CA effettua la ricerca nel registro della California. Le ricerche relative agli Stati Uniti richiedono sempre la suddivisione: un semplice US viene rifiutato. Non fa distinzione tra maiuscole e minuscole; viene normalizzato in maiuscolo.

Maximum string length: 10
Esempio:

"GB"

name
string

Ragione sociale da cercare. È obbligatorio specificare name oppure registration_number.

Maximum string length: 255
Esempio:

"Tesco"

registration_number
string

Numero di registrazione del registro delle imprese da cercare. È obbligatorio indicare name oppure registration_number.

Maximum string length: 100
tier
enum<string>
predefinito:basic

Livello del registro delle imprese sulla cui catena di provider viene eseguita questa ricerca. basic (predefinito) cerca nella catena Lite del paese; shareholders e ubo cercano nella catena dell'assetto proprietario di quel livello, che può essere una fonte diversa, quindi una ricerca Lite vuota non dimostra che l'azienda sia assente dal registro. Per un paese che non offre il livello indicato, la ricerca viene eseguita al livello più alto disponibile fino a quello richiesto. Recupera il candidato dall'endpoint che offre il livello cercato: POST /v3/kyb/select/ (Lite), POST /v3/kyb/shareholders/ o POST /v3/kyb/ubo/.

Opzioni disponibili:
basic,
shareholders,
ubo
Esempio:

"basic"

search_type
enum<string>
predefinito:contains

Strategia di corrispondenza dei nomi applicata dalla ricerca nel registro. contains è l'unico valore accettato: nessuna fonte di registro utilizzata per la ricerca offre una modalità con prefisso o fuzzy, pertanto start_with e fuzzy vengono rifiutati con 400 (not a valid choice).

Opzioni disponibili:
contains
vendor_data
string

Il tuo identificatore per questa ricerca; restituito nella risposta e incluso nel callback webhook.

metadata
object | null

JSON a struttura libera; restituito nella risposta e incluso nel callback del webhook.

webhook_url
string<uri>

Passa la ricerca alla modalità asincrona: l'API risponde immediatamente e invia una chiamata POST di callback kyb.registry_search.resolved non firmata a questo URL quando l'elenco dei candidati è pronto.

Maximum string length: 500

Risposta

Ricerca accettata. La modalità sincrona restituisce l'elenco definitivo dei candidati; la modalità webhook restituisce immediatamente una risposta (spesso search_status: "pending") e consegna l'elenco finale tramite la callback kyb.registry_search.resolved.

request_id
string<uuid>

Con webhook_url: l'ID salvato della richiesta di ricerca, restituito come request_id nel callback kyb.registry_search.resolved. Senza webhook_url: un UUID di correlazione temporaneo (la ricerca non viene memorizzata).

kyb_registry
object
vendor_data
string | null

Eco del vendor_data inviato.

metadata
object | null

Eco del metadata inviato.

created_at
string<date-time>
Ultima modifica il 7 novembre 2026