> ## 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. # API di ricerca nel registro KYB - Ricerca aziende > Didit: POST /v3/kyb/search/ trova aziende candidate. Ricerche riuscite su fonti a pagamento: $0.50 a richiesta; profilo fatturato a parte. 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](https://docs.didit.me/it/standalone-apis/kyb-registry.md#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. > [!NOTE] > > 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: | `tier` cercato | Endpoint che recupera il candidato | | - | - | | `basic` (predefinito) | `POST /v3/kyb/select/` (Lite) | | `shareholders` | `POST /v3/kyb/shareholders/` | | `ubo` | `POST /v3/kyb/ubo/` | ## 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: ```json theme={null} { "detail": "The company registry provider is temporarily unavailable.", "code": "kyb_registry_provider_unavailable" } ``` 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: | Stato | `code` | Quando | | - | - | - | | `400` | `kyb_registry_country_unsupported` | Il paese non ha alcuna fonte di registro aziendale a nessun livello. La limitazione è permanente, quindi ripetere la stessa ricerca non ha mai successo. | | `429` | `kyb_registry_search_limit_reached` | La tua applicazione ha esaurito la quota di 600 ricerche all'ora su fonti di dati aziendali a pagamento e non resta alcuna fonte gratuita per il paese. Attendi la scadenza della finestra oppure inserisci manualmente l'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. ## OpenAPI ````yaml it/openapi-25.json POST /v3/kyb/search/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/kyb/search/: post: tags: - Standalone APIs summary: Ricerca azienda nel registro KYB (autonoma) description: >- Cerca nei registri delle imprese ufficiali le aziende candidate per nome e/o numero di registrazione. Questo è il passaggio 1 del flusso del registro in due passaggi: la **ricerca** restituisce candidati con dati essenziali, poi `POST /v3/kyb/select/` recupera il profilo completo di un candidato. **Fatturazione della ricerca.** Le ricerche riuscite che utilizzano una fonte a pagamento di dati aziendali costano USD 0.50 per richiesta, indipendentemente dal numero di candidati. Risultati vuoti, errori e risultati forniti esclusivamente da altre fonti non vengono addebitati. Il prezzo applicabile viene riservato prima della ricerca; un saldo insufficiente restituisce 403 con codice `insufficient_credits`. Si applicano le tariffe contrattuali concordate e una tariffa di ricerca contrattuale non configurata restituisce 403. Le ricerche in sandbox sono gratuite. La ripetizione di una ricerca riuscita può comportare un nuovo addebito; la consegna del callback non aggiunge costi. Il recupero del profilo viene fatturato separatamente. Questa tariffa di ricerca si applica anche a v2. I candidati hanno sempre `fetch_status: "pending"`: i dati aziendali completi vengono recuperati (e fatturati) solo al momento della selezione. **`kyb_response_id` è effimero.** È un identificatore per singola ricerca, non un ID azienda stabile. Effettua la selezione tempestivamente dopo la ricerca ed esegui nuovamente la ricerca per ottenere un nuovo identificatore invece di memorizzarlo. **`tier` seleziona la catena di provider.** `tier` specifica il livello di registro su cui viene eseguita la ricerca: `basic` (il valore predefinito, la catena Lite), `shareholders` o `ubo`. La ricerca utilizza la catena di provider che serve quel livello e non è sempre la stessa catena letta dalla ricerca Lite, quindi una ricerca Lite vuota non è la prova che il registro non contenga l'azienda: cerca di nuovo al livello necessario. Per un paese che non offre il livello specificato, la ricerca viene eseguita al livello più alto disponibile fino a quello indicato. Recupera il candidato dall'endpoint associato a quel livello: `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` o `POST /v3/kyb/ubo/`. **Autenticazione.** `POST /v3/kyb/search/` (e `/v2/`) accetta la chiave API della tua applicazione nell'intestazione `x-api-key`. L'endpoint ospitato `POST /v1/kyb/search/` è la rotta autenticata tramite sessione chiamata da un flusso di verifica ospitato: risponde `403` a una chiave API e non accetta alcun `tier` — la catena viene selezionata dalla configurazione del registro KYB del workflow. **Due modalità.** - *Sincrona (predefinita):* l'API esegue il polling del registro fino alla risoluzione della ricerca e restituisce l'elenco finale dei candidati (`search_resolved: true`). - *Asincrona:* passando `webhook_url`, l'API risponde immediatamente — solitamente con `search_status: "pending"` e un elenco di candidati vuoto — per poi inviare una POST con callback `kyb.registry_search.resolved` al tuo URL una volta terminata la ricerca nel registro. Il corpo del callback è `{"event_id", "event_type": "kyb.registry_search.resolved", "request_id", "vendor_data", "metadata", "search_status", "search_resolved", "kyb_registry", "timestamp", "created_at"}` — si noti che `timestamp` e `created_at` nel callback sono numeri interi epoch, a differenza del formato ISO di `created_at` in questo endpoint — e viene inviato **non firmato** (intestazione `X-Didit-Unsigned-Callback: true`, senza `X-Signature`). **Codici paese.** ISO 3166-1 alpha-2 (`GB`, `DE`), oltre ai codici di suddivisione `XX-YY` dove i registri sono regionali — ad es. `US-CA` per la California. **Sandbox.** Le chiavi delle applicazioni sandbox restituiscono un singolo candidato statico senza contattare alcun registro. operationId: post_v3_kyb_search parameters: [] requestBody: required: true content: application/json: schema: type: object required: - country_code properties: country_code: type: string maxLength: 10 description: >- 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. example: GB name: type: string maxLength: 255 description: >- Ragione sociale da cercare. È obbligatorio specificare `name` oppure `registration_number`. example: Tesco registration_number: type: string maxLength: 100 description: >- Numero di registrazione del registro delle imprese da cercare. È obbligatorio indicare `name` oppure `registration_number`. tier: type: string enum: - basic - shareholders - ubo default: basic description: >- 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/`. example: basic search_type: type: string enum: - contains default: contains description: >- 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`). vendor_data: type: string description: >- Il tuo identificatore per questa ricerca; restituito nella risposta e incluso nel callback webhook. metadata: type: object nullable: true description: >- JSON a struttura libera; restituito nella risposta e incluso nel callback del webhook. webhook_url: type: string format: uri maxLength: 500 description: >- 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. example: country_code: GB name: Tesco search_type: contains vendor_data: company-1234 responses: '200': description: >- 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`. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- 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: $ref: '#/components/schemas/KYBRegistrySearchResults' vendor_data: type: string nullable: true description: Eco del `vendor_data` inviato. metadata: type: object nullable: true description: Eco del `metadata` inviato. created_at: type: string format: date-time examples: Resolved search: summary: Modalità sincrona — elenco finale dei candidati value: request_id: 0c7e9a40-3a13-4f7e-8a44-9d2e2f1c5b6a kyb_registry: companies: - kyb_response_id: 69aeeb95febb0f1704042259 name: Tesco PLC registration_number: '00445790' status: active type: Public Limited Company risk_level: null fetch_status: pending - kyb_response_id: 69aeeb95febb0f170404225a name: E-TESCO LTD registration_number: '15168476' status: active type: Private Limited Company risk_level: null fetch_status: pending pagination: total: 2 page: 1 per_page: 25 search_status: resolved search_resolved: true vendor_data: company-1234 metadata: null created_at: '2026-06-11T10:40:00.000000+00:00' Pending search (webhook mode): summary: >- `webhook_url` fornito — i candidati arrivano tramite il callback kyb.registry_search.resolved value: request_id: 5f2d8c1b-7e4a-4b9c-9f0d-3a6e8c2b1d4f kyb_registry: companies: [] pagination: total: 0 page: 1 per_page: 25 search_status: pending search_resolved: false vendor_data: company-1234 metadata: source: onboarding created_at: '2026-06-11T10:41:00.000000+00:00' '400': description: >- Errore di validazione. I problemi a livello di campo utilizzano l'involucro standard di DRF; la regola su nome/numero di registrazione genera una segnalazione sotto `non_field_errors`. Un paese non coperto dai registri restituisce `400` con `code: kyb_registry_country_unsupported`. content: application/json: examples: Missing search criteria: summary: Né `name` né `registration_number` forniti value: non_field_errors: - Either 'name' or 'registration_number' is required. Invalid country_code: summary: Deve essere `XX` (alpha-2) o la suddivisione `XX-YY` value: country_code: - country_code must be a 2-letter ISO code. Invalid search_type: summary: È accettato solo `contains` value: search_type: - '"start_with" is not a valid choice.' Invalid webhook_url: summary: '`webhook_url` deve essere un URL valido' value: webhook_url: - Enter a valid URL. Country not covered: summary: Nessun registro delle imprese è disponibile per il paese value: detail: >- Company registry search is not available for this country. Enter the company details manually to continue. code: kyb_registry_country_unsupported '403': description: >- Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{"detail": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Restituito inoltre prima di eseguire la ricerca quando la tariffa di ricerca applicabile non può essere coperta (`code: "insufficient_credits"`), o quando manca una tariffa di ricerca contrattuale. content: application/json: examples: Missing or invalid API key: summary: >- Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata value: detail: You do not have permission to perform this action. '429': description: >- Limite di frequenza superato, oppure la quota di ricerche disponibili è esaurita. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600), con intestazioni `X-RateLimit-*` e `Retry-After`. Separatamente, le ricerche a pagamento nei registri sono limitate a 600 per applicazione all'ora: oltre tale soglia la risposta è `429` con `code: kyb_registry_search_limit_reached`, mentre le ricerche servite esclusivamente da fonti gratuite continuano a funzionare. Attendi e cerca di nuovo più tardi. content: application/json: examples: Write rate limit exceeded: summary: Più di 300 richieste di scrittura nel minuto corrente value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. Search allowance spent: summary: Più di 600 ricerche a pagamento nell'ultima ora value: detail: >- The maximum number of company registry searches for this session has been reached. Enter the company details manually to continue. code: kyb_registry_search_limit_reached schema: type: object properties: detail: type: string code: type: string '502': description: >- Il fornitore del registro delle imprese (KYB) è temporaneamente non disponibile: risposta 5xx, timeout o errore di connessione dal registro a monte. La ricerca non viene fatturata. Riprova più tardi oppure, nel flusso di verifica ospitato di Didit, all'utente viene offerto automaticamente l'inserimento manuale dell'azienda anziché un errore che consente solo un nuovo tentativo. content: application/json: examples: Registry provider outage: summary: Il provider del registro non ha risposto alla ricerca value: detail: >- The KYB registry provider is temporarily unavailable. Please try again shortly. code: kyb_registry_provider_unavailable schema: type: object properties: detail: type: string code: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/kyb/search/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "country_code": "GB", "name": "Tesco", "search_type": "contains", "vendor_data": "company-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.kyb.search( country_code="GB", name="Tesco", search_type="contains", vendor_data="company-1234", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.kyb.search({ country_code: "GB", name: "Tesco", search_type: "contains", vendor_data: "company-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.Search(ctx, didit.KYBSearchParams{\n\tCountryCode: \"GB\",\n\tName: didit.String(\"Tesco\"),\n\tSearchType: didit.Some(didit.KYBSearchParamsSearchType(\"contains\")),\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: |- import me.didit.Didit; import me.didit.types.KybSearchParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.kyb().search(KybSearchParams.builder() .countryCode("GB") .name("Tesco") .searchType(KybSearchParams.SearchType.of("contains")) .vendorData("company-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- kyb->search([ 'country_code' => 'GB', 'name' => 'Tesco', 'search_type' => 'contains', 'vendor_data' => 'company-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.kyb.search( country_code: "GB", name: "Tesco", search_type: "contains", vendor_data: "company-1234" ) puts result.to_h - lang: csharp label: .NET source: |- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Kyb.SearchAsync(new KybSearchParams { CountryCode = "GB", Name = "Tesco", SearchType = new KybSearchParamsSearchType("contains"), VendorData = "company-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: KYBRegistrySearchResults: type: object properties: companies: type: array items: type: object properties: kyb_response_id: type: string nullable: true description: >- Identificatore per questo candidato — passalo a `POST /v3/kyb/select/` per recuperare il profilo completo. Effimero e limitato all'ambito di questa ricerca: non memorizzarlo a lungo termine; effettua nuovamente la ricerca per ottenerne uno nuovo. example: 69aeeb95febb0f1704042259 name: type: string nullable: true description: Ragione sociale registrata. example: Tesco PLC registration_number: type: string nullable: true description: Numero di registrazione nel registro delle imprese. example: '00445790' status: type: string nullable: true description: >- Stato normalizzato dell'azienda nel registro delle imprese (ad es. `active`, `dissolved`, `inactive`, `struck off`). example: active type: type: string nullable: true description: Forma giuridica indicata dal registro. example: Public Limited Company registered_address: type: string nullable: true description: >- Sede legale del candidato, quando il registro ne restituisce una. Utilizzala, insieme al numero di registrazione, per distinguere aziende con lo stesso nome: negli Stati Uniti un candidato può essere registrato nello stato in cui l'azienda opera anziché in quello che hai cercato. example: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA risk_level: type: string nullable: true description: >- Livello di rischio riportato dal registro delle imprese, se disponibile. Di solito `null` al momento della ricerca. fetch_status: type: string nullable: true description: >- Sempre `pending` per i candidati di ricerca: il profilo aziendale completo viene recuperato (e fatturato) solo quando selezioni il candidato. example: pending description: >- Elenco deduplicato dei candidati. Vuoto quando `search_resolved=false` (modalità webhook) o quando non ci sono corrispondenze. pagination: type: object properties: total: type: integer description: Numero di candidati restituiti. page: type: integer per_page: type: integer example: 25 search_status: type: string nullable: true enum: - pending - resolved description: Stato del ciclo di vita della ricerca nel registro delle imprese. search_resolved: type: boolean description: '`true` quando la lista dei candidati è definitiva.' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.