> ## 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 recherche KYB dans le registre des sociétés > Didit : POST /v3/kyb/search/ recherche des entreprises. Recherche réussie sur source payante : $0.50 par requête. Profil facturé à part. 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](https://docs.didit.me/fr/standalone-apis/kyb-registry.md#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. > [!NOTE] > > 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 : | `tier` recherché | Endpoint qui récupère le candidat | | - | - | | `basic` (par défaut) | `POST /v3/kyb/select/` (Lite) | | `shareholders` | `POST /v3/kyb/shareholders/` | | `ubo` | `POST /v3/kyb/ubo/` | ## 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 : ```json theme={null} { "detail": "The company registry provider is temporarily unavailable.", "code": "kyb_registry_provider_unavailable" } ``` 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é : | Statut | `code` | Quand | | - | - | - | | `400` | `kyb_registry_country_unsupported` | Le pays ne dispose d'aucune source de registre des sociétés, à aucun niveau. La limitation est permanente : relancer la même recherche ne réussit jamais. | | `429` | `kyb_registry_search_limit_reached` | Votre application a épuisé son quota de 600 recherches par heure sur des sources de données d'entreprise payantes, et aucune source gratuite n'est disponible pour le pays. Attendez la fin de la fenêtre ou saisissez la société manuellement. | 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. ## OpenAPI ````yaml fr/openapi-25.json POST /v3/kyb/search/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de vérification d'identité. Authentifiez-vous avec l'en-tête x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/kyb/search/: post: tags: - Standalone APIs summary: Recherche d'entreprise au registre KYB (autonome) description: >- Recherchez des entreprises candidates dans les registres des sociétés officiels par nom et/ou numéro d'immatriculation. Il s'agit de l'étape 1 du flux de registre en deux étapes : **search** renvoie des candidats avec des informations succinctes, puis `POST /v3/kyb/select/` récupère le profil complet d'un candidat. **Facturation de la recherche.** Les recherches réussies utilisant une source payante de données d'entreprise coûtent USD 0.50 par requête, quel que soit le nombre de candidats. Les résultats vides, les échecs et les résultats fournis uniquement par d'autres sources ne sont pas facturés. Le prix applicable est réservé avant la recherche ; un solde insuffisant renvoie une erreur 403 avec le code `insufficient_credits`. Les tarifs contractuels s'appliquent lorsqu'ils ont été convenus, et un tarif de recherche contractuel non configuré renvoie une erreur 403. Les recherches en sandbox sont gratuites. Répéter une recherche réussie peut entraîner une nouvelle facturation ; la livraison du rappel n'ajoute pas de frais. La récupération du profil est facturée séparément. Ces frais de recherche s'appliquent également à la v2. Les candidats sont toujours renvoyés avec `fetch_status: "pending"` : les données complètes de l'entreprise ne sont récupérées (et facturées) qu'à la sélection. **`kyb_response_id` est éphémère.** Il s'agit d'un identifiant propre à chaque recherche, et non d'un identifiant d'entreprise stable. Sélectionnez rapidement après la recherche et relancez une recherche pour obtenir un nouvel identifiant au lieu de le stocker. **`tier` sélectionne la chaîne de fournisseurs.** `tier` indique le niveau de registre sur lequel s'exécute la recherche : `basic` (par défaut, la chaîne Lite), `shareholders` ou `ubo`. La recherche utilise la chaîne de fournisseurs qui dessert ce niveau, et il ne s'agit pas toujours de la même chaîne que celle consultée par la recherche Lite ; une recherche Lite vide ne prouve donc pas que le registre ne contient pas l'entreprise — effectuez une nouvelle recherche au niveau dont vous avez besoin. Un pays qui ne propose pas le niveau que vous indiquez fait l'objet d'une recherche au niveau le plus élevé qu'il propose, sans dépasser celui demandé. Récupérez le candidat depuis l'endpoint qui fournit ce niveau : `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` ou `POST /v3/kyb/ubo/`. **Authentification.** `POST /v3/kyb/search/` (et `/v2/`) prend la clé API de votre application dans l'en-tête `x-api-key`. L'endpoint hébergé `POST /v1/kyb/search/` est la route authentifiée par session qu'appelle un flux de vérification hébergé : il répond `403` à une clé API et ne prend aucun `tier` — la configuration du registre KYB du workflow sélectionne la chaîne. **Deux modes.** - *Synchrone (par défaut) :* l'API interroge le registre jusqu'à ce que la recherche aboutisse et renvoie la liste finale des candidats (`search_resolved: true`). - *Asynchrone :* transmettez `webhook_url` et l'API répond immédiatement — généralement avec `search_status: "pending"` et une liste de candidats vide — puis envoie un rappel `kyb.registry_search.resolved` en POST à votre URL lorsque le registre a terminé. Le corps du rappel est `{"event_id", "event_type": "kyb.registry_search.resolved", "request_id", "vendor_data", "metadata", "search_status", "search_resolved", "kyb_registry", "timestamp", "created_at"}` — notez que `timestamp` et `created_at` dans le rappel sont des entiers epoch, contrairement au champ ISO `created_at` de cet endpoint — et est envoyé **non signé** (en-tête `X-Didit-Unsigned-Callback: true`, aucun `X-Signature`). **Codes de pays.** ISO 3166-1 alpha-2 (`GB`, `DE`), ainsi que les codes de subdivision `XX-YY` lorsque les registres sont régionaux — par exemple `US-CA` pour la Californie. **Sandbox.** Les clés des applications sandbox renvoient un candidat statique sans contacter aucun 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: >- 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. example: GB name: type: string maxLength: 255 description: >- Nom de l'entreprise à rechercher. `name` ou `registration_number` est requis. example: Tesco registration_number: type: string maxLength: 100 description: >- Numéro d'immatriculation au registre à rechercher. `name` ou `registration_number` est requis. tier: type: string enum: - basic - shareholders - ubo default: basic description: >- 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/`. example: basic search_type: type: string enum: - contains default: contains description: >- 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`). vendor_data: type: string description: >- Votre identifiant pour cette recherche ; renvoyé en écho et inclus dans le rappel de webhook. metadata: type: object nullable: true description: >- JSON libre ; renvoyé en écho et inclus dans le callback du webhook. webhook_url: type: string format: uri maxLength: 500 description: >- 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. example: country_code: GB name: Tesco search_type: contains vendor_data: company-1234 responses: '200': description: >- 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`. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- 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: $ref: '#/components/schemas/KYBRegistrySearchResults' vendor_data: type: string nullable: true description: Valeur renvoyée de `vendor_data` que vous avez envoyé. metadata: type: object nullable: true description: Écho des `metadata` que vous avez envoyées. created_at: type: string format: date-time examples: Resolved search: summary: Mode synchrone — liste finale des 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: >- `webhook_url` fournie — les candidats arrivent via le 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: >- Erreur de validation. Les problèmes au niveau des champs utilisent l'enveloppe standard de DRF ; la règle relative au nom/numéro d'immatriculation est signalée sous `non_field_errors`. Un pays non couvert par les registres renvoie `400` avec `code: kyb_registry_country_unsupported`. content: application/json: examples: Missing search criteria: summary: Ni `name` ni `registration_number` n'ont été fournis value: non_field_errors: - Either 'name' or 'registration_number' is required. Invalid country_code: summary: Doit être `XX` (alpha-2) ou une subdivision `XX-YY` value: country_code: - country_code must be a 2-letter ISO code. Invalid search_type: summary: Seul `contains` est accepté value: search_type: - '"start_with" is not a valid choice.' Invalid webhook_url: summary: '`webhook_url` doit être une URL valide' value: webhook_url: - Enter a valid URL. Country not covered: summary: Aucun registre des sociétés ne couvre ce pays 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: "Permission refusée. Renvoyé lorsque l'en-tête `x-api-key` est manquant\_; une clé incorrecte, révoquée ou expirée renvoie `401`. Une clé manquante renvoie `403` avec `{\"detail\": ...}`\_; une clé incorrecte, révoquée ou expirée renvoie `401`. Également renvoyé avant la recherche lorsque les frais de recherche applicables ne peuvent pas être couverts (`code: \"insufficient_credits\"`), ou lorsqu'un tarif de recherche contractuel est manquant." content: application/json: examples: Missing or invalid API key: summary: Aucun en-tête `x-api-key`, ou la clé est non valide/révoquée value: detail: You do not have permission to perform this action. '429': description: >- Limite de débit dépassée, ou quota de recherche épuisé. Les endpoints POST/PATCH/DELETE partagent un budget de 300 requêtes d'écriture par minute par clé API (la création de transactions et l'ingestion d'événements disposent d'un budget distinct de 600), avec les en-têtes `X-RateLimit-*` et `Retry-After`. Par ailleurs, les recherches payantes dans les registres sont limitées à 600 par application par heure : au-delà, la réponse est `429` avec `code: kyb_registry_search_limit_reached`, et les recherches traitées uniquement par des sources gratuites fonctionnent toujours. Attendez et relancez la recherche plus tard. content: application/json: examples: Write rate limit exceeded: summary: >- Plus de 300 requêtes d'écriture au cours de la minute actuelle value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. Search allowance spent: summary: >- Plus de 600 recherches payantes au cours de la dernière heure 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: "Le fournisseur de registre KYB est temporairement indisponible\_: une réponse 5xx, un délai d'attente dépassé ou une erreur de connexion du registre en amont. La recherche n'est pas facturée. Réessayez plus tard, ou, dans le flux de vérification hébergé de Didit, l'utilisateur se voit automatiquement proposer la saisie manuelle de l'entreprise au lieu d'une erreur indiquant uniquement de réessayer." content: application/json: examples: Registry provider outage: summary: Le fournisseur de registre n'a pas répondu à la recherche 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: >- Identifiant pour ce candidat — transmettez-le à `POST /v3/kyb/select/` pour récupérer le profil complet. Éphémère et limité à cette recherche : ne le stockez pas à long terme ; relancez une recherche pour en obtenir un nouveau. example: 69aeeb95febb0f1704042259 name: type: string nullable: true description: Raison sociale enregistrée. example: Tesco PLC registration_number: type: string nullable: true description: Numéro d'immatriculation au registre. example: '00445790' status: type: string nullable: true description: >- Statut normalisé de l'entreprise auprès du registre (par exemple `active`, `dissolved`, `inactive`, `struck off`). example: active type: type: string nullable: true description: Forme juridique telle que déclarée par le registre. example: Public Limited Company registered_address: type: string nullable: true description: >- Adresse enregistrée du candidat, lorsque le registre en renvoie une. Utilisez-la, avec le numéro d'immatriculation, pour distinguer les entreprises homonymes : aux États-Unis, un candidat peut être répertorié dans l'État où l'entreprise opère plutôt que dans celui que vous avez recherché. example: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA risk_level: type: string nullable: true description: >- Niveau de risque indiqué par le registre, lorsqu'il est disponible. Généralement `null` au moment de la recherche. fetch_status: type: string nullable: true description: >- Toujours `pending` pour les candidats issus de la recherche — le profil complet de l'entreprise n'est récupéré (et facturé) que lorsque vous sélectionnez le candidat. example: pending description: >- Liste de candidats dédupliquée. Vide tant que `search_resolved=false` (mode webhook) ou lorsqu'aucun résultat ne correspond. pagination: type: object properties: total: type: integer description: Nombre de candidats retournés. page: type: integer per_page: type: integer example: 25 search_status: type: string nullable: true enum: - pending - resolved description: Statut du cycle de vie de la recherche au registre. search_resolved: type: boolean description: '`true` dès que la liste de candidats est définitive.' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.