Passer au contenu principal
POST
curl
Utilisez d’abord cet endpoint pour trouver les candidats correspondants dans les registres des sociétés. La recherche ne crée pas de Manual Check enregistré. Les recherches autonomes réussies utilisant une source de données d’entreprise payante coûtent $0.50 par requête, quel que soit le nombre de candidats. Les recherches vides, les recherches échouées et les résultats fournis uniquement par d’autres sources ne sont pas facturés. Une récupération ultérieure du profil est facturée séparément. Pour une recherche pouvant utiliser une source payante, Didit vérifie le solde et réserve le tarif de recherche applicable avant de contacter le registre. Un solde insuffisant renvoie 403 avec code: "insufficient_credits". La facturation contractuelle suit votre tarif de recherche convenu ; un tarif contractuel non configuré est rejeté avant la recherche. Les recherches en sandbox sont gratuites. Chaque recherche réussie répétée constitue une nouvelle requête facturable ; la livraison du rappel n’ajoute aucun frais de recherche supplémentaire. Si vous envoyez webhook_url, Didit peut répondre immédiatement pendant que le fournisseur résout la recherche, puis publier les candidats sur votre URL de rappel dès qu’ils sont prêts. Le rappel n’est pas signé par conception : vous n’avez donc pas besoin de configurer un secret de webhook pour cette notification de recherche. Voir l’exemple de payload du rappel de recherche. Après avoir choisi le bon kyb_response_id, appelez POST /v3/kyb/select/ (Lite), POST /v3/kyb/shareholders/ ou POST /v3/kyb/ubo/ pour récupérer le profil de registre facturable au niveau dont vous avez besoin.
Le fetch_status de chaque candidat est pending au moment de la recherche et reste pending jusqu’à ce que vous sélectionniez ce candidat : la recherche se contente de lister les candidats, et la sélection récupère le profil complet. N’interrogez pas la recherche en attendant qu’il soit résolu.Le kyb_response_id est un identifiant opaque et éphémère, limité à une seule requête de recherche : renvoyez-le exactement tel que vous l’avez reçu, ne l’analysez jamais et n’en déduisez rien, et attendez-vous à ce qu’une recherche répétée renvoie de nouveaux identifiants. Sélectionnez le candidat rapidement après la recherche, et utilisez registration_number lorsque vous avez besoin d’un identifiant stable pour la société elle-même.

Niveau de recherche

tier sélectionne le niveau de registre dont la chaîne de fournisseurs exécute la recherche : basic (par défaut, la chaîne Lite), shareholders ou ubo. La liste des candidats provient de la chaîne de ce niveau, qui n’est pas toujours la source lue par la recherche Lite ; une recherche Lite vide ne prouve donc pas que le registre ne contient pas la société. Relancez la recherche au niveau dont vous avez besoin. Lorsque le pays ne propose pas le niveau demandé, la recherche s’exécute au niveau le plus élevé qu’il propose, sans dépasser celui-ci. Un pays sans aucune donnée de registre n’est pas proposé pour les vérifications de registre ; poursuivez alors avec la saisie manuelle de la société. Effectuez la recherche au niveau que vous comptez acheter, puis récupérez le candidat depuis l’endpoint qui le vend :

search_type

search_type n’accepte que contains, qui est la valeur par défaut. Les sources de registre derrière la recherche font correspondre un nom de société par inclusion ; start_with et fuzzy sont donc rejetés avec 400 ("start_with" is not a valid choice) au lieu d’être silencieusement traités comme contains. Envoyez registration_number pour une correspondance exacte de la société.

Recherche hébergée et recherche autonome

POST /v1/kyb/search/ est la recherche qu’exécute un flux de vérification hébergé : elle est authentifiée par la session de vérification, renvoie 403 lorsqu’elle est appelée avec une clé API, et n’accepte aucun tier ; c’est la configuration du registre KYB du workflow qui choisit la chaîne. L’API autonome appelle POST /v2/kyb/search/ ou POST /v3/kyb/search/ avec votre x-api-key. L’entrée tier et les endpoints de sélection par niveau sont la façon dont une intégration autonome accède aux mêmes candidats, au niveau dont elle a besoin.

Gérer les indisponibilités du registre

Si le fournisseur de registre est temporairement indisponible, l’endpoint renvoie 502 avec un code stable lisible par machine :
Lorsque vous recevez ce code, laissez l’utilisateur poursuivre avec la saisie manuelle de la société ou demandez-lui de réessayer plus tard. Séparez les erreurs de validation : une entrée de recherche invalide renvoie 400 et n’utilise pas ce code d’indisponibilité.

Gérer les pays non pris en charge et les limites de recherche

Deux autres codes stables vous indiquent d’arrêter les nouvelles tentatives et de poursuivre avec la saisie manuelle de la société : Dans le flux hébergé, chaque étape de registre autorise 3 recherches sur une source de données d’entreprise payante. Après la troisième, le demandeur se voit proposer la saisie manuelle. Sélectionner un candidat qui est un enregistrement de marque et non une société renvoie 400 avec code: "kyb_registry_entry_not_a_company". Choisissez plutôt une société parmi les résultats de recherche.

Autorisations

x-api-key
string
header
requis

La clé API de votre application, issue de Développeurs -> Clés API dans la Business Console. La clé principale dispose d'un accès complet. Une clé nommée peut être restreinte : aucun, lecture ou écriture par ressource, limitée à certains workflows ou aux sessions approuvées, à une liste d'adresses IP et à une date d'expiration. 401 signifie que la clé est incorrecte, révoquée ou expirée ; 403 signifie qu'aucune clé n'a été envoyée, que la clé n'a pas accès à cette ressource ou action, ou que la requête provient d'une adresse hors de sa liste d'IP ; 404 sur une route de session signifie que la session est hors des workflows ou des statuts de la clé. Une clé sans accès aux médias reçoit les URL d'images, de vidéos et de PDF à null, et une clé sans accès en écriture aux sessions reçoit les liens et tokens de session à null. Voir https://docs.didit.me/console/api-keys.

Corps

application/json
country_code
string
requis

Code ISO 3166-1 alpha-2 du pays dont le registre des sociétés doit être interrogé. Par exemple, GB. Lorsque les registres des sociétés fonctionnent au niveau de l'État ou de la province, ajoutez le code de subdivision ISO 3166-2 sous la forme XX-YY : US-CA effectue la recherche dans le registre de Californie. Les recherches aux États-Unis requièrent toujours la subdivision — un code US seul est rejeté. Insensible à la casse ; normalisé en majuscules.

Maximum string length: 10
Exemple:

"GB"

name
string

Nom de l'entreprise à rechercher. name ou registration_number est requis.

Maximum string length: 255
Exemple:

"Tesco"

registration_number
string

Numéro d'immatriculation au registre à rechercher. name ou registration_number est requis.

Maximum string length: 100
tier
enum<string>
défaut:basic

Niveau de registre dont la chaîne de fournisseurs est utilisée pour cette recherche. basic (par défaut) effectue la recherche sur la chaîne Lite du pays ; shareholders et ubo effectuent la recherche sur la chaîne d'actionnariat de ce niveau, qui peut provenir d'une source différente, de sorte qu'une recherche Lite vide ne prouve pas que l'entreprise est absente du registre. Pour un pays qui ne propose pas le niveau spécifié, la recherche s'effectue au niveau le plus élevé proposé jusqu'à celui-ci. Récupérez le candidat à partir de l'endpoint qui fournit le niveau recherché : POST /v3/kyb/select/ (Lite), POST /v3/kyb/shareholders/ ou POST /v3/kyb/ubo/.

Options disponibles:
basic,
shareholders,
ubo
Exemple:

"basic"

search_type
enum<string>
défaut:contains

Stratégie de correspondance des noms appliquée par la recherche dans le registre. contains est la seule valeur acceptée : aucune source de registre derrière la recherche ne propose de mode préfixe ou flou, start_with et fuzzy sont donc rejetés avec 400 (not a valid choice).

Options disponibles:
contains
vendor_data
string

Votre identifiant pour cette recherche ; renvoyé en écho et inclus dans le rappel de webhook.

metadata
object | null

JSON libre ; renvoyé en écho et inclus dans le callback du webhook.

webhook_url
string<uri>

Bascule la recherche en mode asynchrone : l'API répond immédiatement et envoie un rappel POST non signé kyb.registry_search.resolved à cette URL lorsque la liste des candidats est prête.

Maximum string length: 500

Réponse

Recherche acceptée. Le mode synchrone renvoie la liste des candidats résolus ; le mode webhook renvoie immédiatement (souvent search_status: "pending") et délivre la liste finale via le callback kyb.registry_search.resolved.

request_id
string<uuid>

Avec webhook_url : l'identifiant de requête de recherche persistant, renvoyé sous la forme request_id dans le rappel kyb.registry_search.resolved. Sans webhook_url : un UUID de corrélation éphémère (la recherche n'est pas stockée).

kyb_registry
object
vendor_data
string | null

Valeur renvoyée de vendor_data que vous avez envoyé.

metadata
object | null

Écho des metadata que vous avez envoyées.

created_at
string<date-time>
Dernière modification le 7 novembre 2026