> ## 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 de cerca al registre mercantil KYB - Cerca d'empreses > Didit: POST /v3/kyb/search/ troba empreses. Cerques satisfactòries en fonts de pagament: $0.50 per sol·licitud; el perfil es factura a part. Utilitza primer aquest endpoint per trobar els candidats del registre mercantil que coincideixen. La cerca no crea cap Manual Check guardada. Les cerques autònomes satisfactòries que utilitzen una font de dades d'empreses de pagament costen **\$0.50 per sol·licitud**, independentment del nombre de candidats. Les cerques sense resultats, les cerques fallides i els resultats servits només per altres fonts no es cobren. La recuperació posterior d'un perfil es factura per separat. Per a una cerca que pot utilitzar una font de pagament, Didit comprova i reserva el preu de cerca aplicable abans de contactar amb el registre. Un saldo insuficient retorna `403` amb `code: "insufficient_credits"`. La facturació contractual segueix la tarifa de cerca acordada; una tarifa contractual no configurada es rebutja abans de la cerca. Les cerques al sandbox són gratuïtes. Cada cerca repetida satisfactòria és una sol·licitud nova facturable; el lliurament del callback no afegeix cap altre càrrec de cerca. Si envies `webhook_url`, Didit pot retornar immediatament mentre el proveïdor resol la cerca, i després enviarà els candidats a la teva URL de callback quan estiguin llestos. El callback no va signat per disseny, de manera que no cal que configuris un secret de webhook per a aquesta notificació de cerca. Consulta l'[exemple de payload del callback de cerca](https://docs.didit.me/ca/standalone-apis/kyb-registry.md#callback-de-la-cerca). Després de triar el `kyb_response_id` correcte, crida `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` o `POST /v3/kyb/ubo/` per recuperar el perfil del registre facturable al nivell que necessitis. > [!NOTE] > > El `fetch_status` de cada candidat és `pending` en el moment de la cerca i es manté `pending` fins que selecciones aquest candidat: la cerca només llista candidats, i la selecció és la que recupera el perfil complet. No facis polling de la cerca esperant que es resolgui. > > El `kyb_response_id` és un identificador opac i efímer, limitat a una sola sol·licitud de cerca: torna'l exactament tal com l'has rebut, no l'analitzis mai ni en derivis res del seu contingut, i espera que repetir la mateixa cerca retorni identificadors nous. Selecciona el candidat aviat després de cercar, i utilitza `registration_number` quan necessitis un identificador estable de l'empresa. ## Nivell de cerca `tier` indica el nivell de registre en què s'executa la cerca, és a dir, la cadena de proveïdors d'aquell nivell: `basic` (per defecte, la cadena Lite), `shareholders` o `ubo`. La llista de candidats prové de la cadena d'aquell nivell, i no sempre és la mateixa font que llegeix la cerca Lite; per això, una cerca Lite buida no demostra que el registre no tingui l'empresa: torna a cercar al nivell que necessites. Quan el país no ofereix el nivell que indiques, la cerca s'executa en el nivell més alt que ofereix fins a aquest. Un país sense cap dada de registre no s'ofereix per a comprovacions de registre; continua amb l'entrada manual de l'empresa. Fes la cerca al nivell que tens previst comprar i després recupera el candidat des de l'endpoint que el ven: | `tier` que has cercat | Endpoint que recupera el candidat | | - | - | | `basic` (per defecte) | `POST /v3/kyb/select/` (Lite) | | `shareholders` | `POST /v3/kyb/shareholders/` | | `ubo` | `POST /v3/kyb/ubo/` | ## search\_type `search_type` accepta només `contains`, i aquest és el valor per defecte. Les fonts de registre que hi ha darrere de la cerca fan coincidir el nom de l'empresa per inclusió, de manera que `start_with` i `fuzzy` es rebutgen amb `400` (`"start_with" is not a valid choice`) en lloc de tractar-se silenciosament com a `contains`. Envia `registration_number` per a una coincidència exacta de l'empresa. ## Cerca allotjada i autònoma `POST /v1/kyb/search/` és la cerca que executa un flux de verificació allotjat: s'autentica amb la sessió de verificació, respon `403` a una clau d'API i no admet `tier`; la configuració del registre KYB del flux de treball és la que tria la cadena. L'API autònoma crida `POST /v2/kyb/search/` o `POST /v3/kyb/search/` amb la teva `x-api-key`; l'entrada `tier` i els endpoints de selecció per nivell són la manera com una integració autònoma arriba als mateixos candidats, al nivell que necessita. ## Gestió d'interrupcions del registre Si el proveïdor del registre no està disponible temporalment, l'endpoint retorna `502` amb un codi estable i llegible per màquines: ```json theme={null} { "detail": "The company registry provider is temporarily unavailable.", "code": "kyb_registry_provider_unavailable" } ``` Quan rebis aquest codi, deixa que l'usuari continuï amb l'entrada manual de l'empresa o demana-li que ho torni a provar més tard. Mantén separats els errors de validació: una entrada de cerca no vàlida retorna `400` i no utilitza aquest codi d'interrupció. ## Gestió de països no compatibles i límits de cerca Hi ha dos codis estables més que t'indiquen que deixis de reintentar i continuïs amb l'entrada manual de l'empresa: | Estat | `code` | Quan | | - | - | - | | `400` | `kyb_registry_country_unsupported` | El país no té cap font del registre mercantil a cap nivell. La limitació és permanent, de manera que reintentar la mateixa cerca mai no tindrà èxit. | | `429` | `kyb_registry_search_limit_reached` | La teva aplicació ha esgotat la quota de 600 cerques per hora en fonts de dades d'empreses de pagament i no queda cap font gratuïta per al país. Espera que passi la finestra o introdueix l'empresa manualment. | En el flux de verificació allotjat, cada pas de registre permet 3 cerques en una font de dades d'empreses de pagament. Després de la tercera, se li ofereix a la persona sol·licitant l'entrada manual. Seleccionar un candidat que és un registre de marca i no una empresa retorna `400` amb `code: "kyb_registry_entry_not_a_company"`. Tria una empresa dels resultats de la cerca. ## OpenAPI ````yaml ca/openapi-25.json POST /v3/kyb/search/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/kyb/search/: post: tags: - Standalone APIs summary: Cerca d'empresa al registre mercantil per a KYB (independent) description: >- Cerca empreses candidates als registres mercantils oficials per nom i/o número de registre. Aquest és el pas 1 del flux de registre en dos passos: **search** retorna candidats simplificats i, després, `POST /v3/kyb/select/` obté el perfil complet d'un candidat. **Facturació de la cerca.** Les cerques satisfactòries que utilitzen una font de dades d'empresa de pagament costen USD 0.50 per sol·licitud, independentment del nombre de candidats. Els resultats buits, les fallades i els resultats servits només per altres fonts no es cobren. El preu aplicable es reserva abans de la cerca; un saldo insuficient retorna 403 amb el codi `insufficient_credits`. S'apliquen les tarifes per contracte quan s'hagi acordat, i una tarifa de cerca per contracte no configurada retorna 403. Les cerques al sandbox són gratuïtes. Repetir una cerca satisfactòria pot comportar un altre càrrec; el lliurament del callback no afegeix cap càrrec. L'obtenció del perfil es factura per separat. Aquesta tarifa de cerca també s'aplica a la v2. Els candidats sempre es retornen amb `fetch_status: "pending"`: les dades completes de l'empresa només s'obtenen (i es facturen) en seleccionar. **`kyb_response_id` és efímer.** És un identificador per a cada cerca, no un id d'empresa estable. Fes la selecció ràpidament després de cercar i torna a cercar per obtenir un identificador nou en lloc d'emmagatzemar-lo. **`tier` tria la cadena de proveïdors.** `tier` indica el nivell de registre en què s'executa la cerca: `basic` (per defecte, la cadena Lite), `shareholders` o `ubo`. La cerca utilitza la cadena de proveïdors que dona servei a aquest nivell, i no sempre és la mateixa cadena que llegeix la cerca Lite, de manera que una cerca Lite buida no és una prova que el registre no contingui l'empresa — torna a cercar al nivell que necessitis. Un país que no ofereixi el nivell que indiques es cerca al nivell més alt que ofereixi fins a aquest. Obtén el candidat des de l'endpoint que ven aquest nivell: `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` o `POST /v3/kyb/ubo/`. **Autenticació.** `POST /v3/kyb/search/` (i `/v2/`) rep la clau d'API de la teva aplicació a la capçalera `x-api-key`. L'endpoint allotjat `POST /v1/kyb/search/` és la ruta autenticada per sessió que crida un flux de verificació allotjat: respon `403` a una clau d'API i no rep cap `tier` — la configuració del registre KYB del flux de treball tria la cadena. **Dos modes.** - *Síncron (per defecte):* l'API consulta repetidament el registre fins que la cerca es resol i retorna la llista final de candidats (`search_resolved: true`). - *Asíncron:* passa `webhook_url` i l'API respon immediatament — normalment amb `search_status: "pending"` i una llista buida de candidats — i després fa un POST amb un callback `kyb.registry_search.resolved` a la teva URL quan el registre acaba. El cos del callback és `{"event_id", "event_type": "kyb.registry_search.resolved", "request_id", "vendor_data", "metadata", "search_status", "search_resolved", "kyb_registry", "timestamp", "created_at"}` — tingues en compte que `timestamp` i `created_at` al callback són enters epoch, a diferència del `created_at` en format ISO d'aquest endpoint — i s'envia **sense signar** (capçalera `X-Didit-Unsigned-Callback: true`, sense `X-Signature`). **Codis de país.** ISO 3166-1 alpha-2 (`GB`, `DE`), més codis de subdivisió `XX-YY` on els registres són regionals — p. ex., `US-CA` per a Califòrnia. **Sandbox.** Les claus d'aplicacions del sandbox retornen un candidat estàtic sense contactar amb cap registre. 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: >- Codi ISO 3166-1 alfa-2 del país el registre mercantil del qual es vol cercar. Per exemple, `GB`. On els registres mercantils operen a escala estatal o provincial, afegeix el codi de subdivisió ISO 3166-2 en format `XX-YY`: `US-CA` cerca al registre de Califòrnia. Les cerques als Estats Units sempre requereixen la subdivisió; un valor simple `US` es rebutja. No distingeix entre majúscules i minúscules; es normalitza a majúscules. example: GB name: type: string maxLength: 255 description: >- Nom de l'empresa a cercar. Cal indicar `name` o `registration_number`. example: Tesco registration_number: type: string maxLength: 100 description: >- Número de registre del registre que cal cercar. Es requereix `name` o bé `registration_number`. tier: type: string enum: - basic - shareholders - ubo default: basic description: >- Nivell del registre en la cadena de proveïdors en què s'executa aquesta cerca. `basic` (per defecte) cerca a la cadena Lite del país; `shareholders` i `ubo` cerquen a la cadena de titularitat d'aquest nivell, que pot ser una font diferent, de manera que una cerca Lite buida no demostra que l'empresa no figuri al registre. En un país que no ofereixi el nivell indicat, es cerca al nivell més alt que ofereixi fins a aquest. Recupera el candidat des de l'endpoint que ven el nivell que has cercat: `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: >- Estratègia de coincidència de noms aplicada per la cerca al registre. `contains` és l'únic valor acceptat: cap font de registre darrere de la cerca ofereix un mode de prefix o difús (fuzzy), de manera que `start_with` i `fuzzy` es rebutgen amb `400` (`not a valid choice`). vendor_data: type: string description: >- El teu identificador per a aquesta consulta; es retorna tal com s'ha enviat i s'inclou al callback del webhook. metadata: type: object nullable: true description: >- JSON de format lliure; retornat com a resposta i inclòs a la crida de retorn del webhook. webhook_url: type: string format: uri maxLength: 500 description: >- Canvia la cerca al mode asíncron: l'API respon immediatament i envia mitjançant POST un callback no signat `kyb.registry_search.resolved` a aquesta URL quan la llista de candidats està a punt. example: country_code: GB name: Tesco search_type: contains vendor_data: company-1234 responses: '200': description: >- Cerca acceptada. El mode síncron retorna la llista de candidats resolta; el mode webhook retorna immediatament (sovint `search_status: "pending"`) i lliura la llista final mitjançant el callback `kyb.registry_search.resolved`. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- Amb `webhook_url`: l'identificador persistent de la sol·licitud de cerca, retornat com a `request_id` al callback de `kyb.registry_search.resolved`. Sense `webhook_url`: un UUID de correlació transitori (la cerca no s'emmagatzema). kyb_registry: $ref: '#/components/schemas/KYBRegistrySearchResults' vendor_data: type: string nullable: true description: Ressò del `vendor_data` que has enviat. metadata: type: object nullable: true description: Ressò de les `metadata` que has enviat. created_at: type: string format: date-time examples: Resolved search: summary: Mode síncron — llista final de candidats 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: >- S'ha proporcionat `webhook_url` — els candidats arriben a través del 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: >- Error de validació. Els problemes a nivell de camp utilitzen l'embolcall estàndard de DRF; la regla de nom/número de registre es notifica sota `non_field_errors`. Un país que els registres no cobreixen respon `400` amb `code: kyb_registry_country_unsupported`. content: application/json: examples: Missing search criteria: summary: No s'ha proporcionat ni `name` ni `registration_number` value: non_field_errors: - Either 'name' or 'registration_number' is required. Invalid country_code: summary: Ha de ser `XX` (alfa-2) o subdivisió `XX-YY` value: country_code: - country_code must be a 2-letter ISO code. Invalid search_type: summary: Només s'accepta `contains` value: search_type: - '"start_with" is not a valid choice.' Invalid webhook_url: summary: '`webhook_url` ha de ser un URL vàlid' value: webhook_url: - Enter a valid URL. Country not covered: summary: No hi ha cap registre mercantil per a aquest país 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: >- Permís denegat. Es retorna quan falta la capçalera `x-api-key`; una clau incorrecta, revocada o caducada retorna `401`. Si falta la clau es retorna `403` amb `{"detail": ...}`; una clau incorrecta, revocada o caducada retorna `401`. També es retorna abans de fer la cerca quan no es pot cobrir la tarifa de cerca aplicable (`code: "insufficient_credits"`), o quan falta una tarifa de cerca per contracte. content: application/json: examples: Missing or invalid API key: summary: >- Sense capçalera `x-api-key`, o la clau no és vàlida/s'ha revocat value: detail: You do not have permission to perform this action. '429': description: >- S'ha superat el límit de freqüència o s'ha esgotat el límit de cerques disponibles. Els endpoints POST/PATCH/DELETE comparteixen un pressupost de 300 sol·licituds d'escriptura per minut per clau d'API (la creació de transaccions i la ingesta d'esdeveniments tenen un pressupost independent de 600), amb les capçaleres `X-RateLimit-*` i `Retry-After`. A part, les cerques de pagament al registre mercantil estan limitades a 600 per aplicació i per hora: passat aquest límit, la resposta és `429` amb `code: kyb_registry_search_limit_reached`, i les cerques ateses exclusivament per fonts gratuïtes continuen funcionant. Espera i torna a cercar més tard. content: application/json: examples: Write rate limit exceeded: summary: Més de 300 sol·licituds d'escriptura en el minut actual value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. Search allowance spent: summary: Més de 600 cerques de pagament en l'última hora 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: >- El proveïdor del registre de KYB no està disponible temporalment: una resposta 5xx, temps d'espera esgotat o fallada de connexió del registre d'origen. La cerca no es factura. Torna-ho a provar més tard, o bé, en el flux de verificació allotjat de Didit, a l'usuari se li ofereix automàticament la introducció manual de l'empresa en lloc d'un error que només permeti reintentar. content: application/json: examples: Registry provider outage: summary: El proveïdor del registre no ha respost a la cerca 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: >- Identificador d'aquest candidat; passa'l a `POST /v3/kyb/select/` per obtenir el perfil complet. És efímer i està limitat a aquesta cerca: no l'emmagatzemis a llarg termini; torna a cercar per obtenir-ne un de nou. example: 69aeeb95febb0f1704042259 name: type: string nullable: true description: Nom de l'empresa registrada. example: Tesco PLC registration_number: type: string nullable: true description: Número de registre del registre mercantil. example: '00445790' status: type: string nullable: true description: >- Estat registral normalitzat de l'empresa (p. ex. `active`, `dissolved`, `inactive`, `struck off`). example: active type: type: string nullable: true description: Forma jurídica segons el que indica el registre. example: Public Limited Company registered_address: type: string nullable: true description: >- Adreça registrada del candidat, quan el registre en retorna una. Utilitza-la, juntament amb el número de registre, per distingir empreses amb el mateix nom: als Estats Units un candidat pot figurar sota l'estat on opera l'empresa en lloc de l'estat que has cercat. example: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA risk_level: type: string nullable: true description: >- Nivell de risc notificat pel registre, quan estigui disponible. Normalment `null` en el moment de la cerca. fetch_status: type: string nullable: true description: >- Sempre `pending` per als candidats de cerca; el perfil complet de l'empresa només s'obté (i es factura) quan selecciones el candidat. example: pending description: >- Llista de candidats deduplicada. Buida mentre `search_resolved=false` (mode webhook) o quan no hi ha hagut cap coincidència. pagination: type: object properties: total: type: integer description: Nombre de candidats retornats. page: type: integer per_page: type: integer example: 25 search_status: type: string nullable: true enum: - pending - resolved description: Estat del cicle de vida de la cerca al registre. search_resolved: type: boolean description: '`true` un cop la llista de candidats és definitiva.' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.