Saltar al contingut principal
POST
curl
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. 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.
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:

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:
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: 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.

Autoritzacions

x-api-key
string
header
requerit

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.

Cos

application/json
country_code
string
requerit

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.

Maximum string length: 10
Exemple:

"GB"

name
string

Nom de l'empresa a cercar. Cal indicar name o registration_number.

Maximum string length: 255
Exemple:

"Tesco"

registration_number
string

Número de registre del registre que cal cercar. Es requereix name o bé registration_number.

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

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/.

Opcions disponibles:
basic,
shareholders,
ubo
Exemple:

"basic"

search_type
enum<string>
predeterminat:contains

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

Opcions disponibles:
contains
vendor_data
string

El teu identificador per a aquesta consulta; es retorna tal com s'ha enviat i s'inclou al callback del webhook.

metadata
object | null

JSON de format lliure; retornat com a resposta i inclòs a la crida de retorn del webhook.

webhook_url
string<uri>

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.

Maximum string length: 500

Resposta

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.

request_id
string<uuid>

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
object
vendor_data
string | null

Ressò del vendor_data que has enviat.

metadata
object | null

Ressò de les metadata que has enviat.

created_at
string<date-time>
Darrera modificació el 7 de novembre del 2026