API registre KYB : recherche et sélection d'entreprises

Endpoints et facturation

Les recherches autonomes réussies utilisant une source de données d’entreprises payante sont facturées $0.50 par requête, quel que soit le nombre de candidats. Les résultats 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. La récupération est vendue en trois niveaux de données, chacun avec son propre endpoint, tarifés par pays (tarifs par pays) :

Endpoint	Ce que vous obtenez	Tarif
`POST /v3/kyb/search/`	Entreprises candidates : nom, numéro d’immatriculation, statut, type	$0.50 lorsque des résultats de sources payantes sont renvoyés
`POST /v3/kyb/select/`	Lite : le profil de l’entreprise (identifiants, statut, forme juridique, date de constitution, adresse du siège, activité, coordonnées) et les dirigeants	Tarif Lite : $2.00-$3.00 selon le pays
`POST /v3/kyb/shareholders/`	Lite plus les actionnaires directs avec leurs tranches de détention	Tarif Shareholders : $5.00-$22.00 selon le pays
`POST /v3/kyb/ubo/`	Shareholders plus les bénéficiaires effectifs ultimes, identifiés via la chaîne de détention	Tarif UBO : $9.00-$96.00 selon le pays

select correspond au niveau Lite : c’est ce qu’un workflow KYB hébergé facture pour une vérification de registre au niveau Lite, et il conserve le contrat qu’il a toujours eu. L’Europe désigne l’EEE, le Royaume-Uni et la Suisse. Une recherche Shareholders ou UBO interroge la source de données d’actionnariat qui fournit ce niveau. Lorsque cette source indique qu’elle ne détient pas l’entreprise, la recherche interroge aussi les autres sources de registres du pays, afin qu’une entreprise absente de la source d’actionnariat soit tout de même proposée comme candidat au lieu de se terminer par une saisie manuelle. Les candidats trouvés de cette façon conservent le niveau que vous avez demandé : leur récupération revérifie la source d’actionnariat et, si elle ne détient toujours pas l’entreprise, le profil Lite est livré et facturé, avec registry_ownership_status: "not_held".

Vous payez le niveau livré. Chaque réponse contient registry_tier_requested et registry_tier_delivered. Lorsque les registres du pays ne détiennent aucune donnée d’actionnariat, ou lorsque le registre ne contient aucun enregistrement d’actionnariat pour l’entreprise sélectionnée, une demande d’actionnariat est livrée et facturée au niveau le plus élevé disponible (généralement Lite), et registry_ownership_status indique la raison. Une demande UBO dont le rapport obtenu ne désigne aucune personne physique comme bénéficiaire effectif est livrée et facturée au niveau Shareholders.

Gestion des versions. Les endpoints Shareholders et UBO n’existent que sur /v3/. Les frais de recherche autonome s’appliquent aussi à /v2/kyb/search/ ; la récupération du profil est facturée séparément.

Statut de l’actionnariat

registry_ownership_status indique ce qu’il est advenu de la partie actionnariat d’une demande Shareholders ou UBO :

Valeur	Signification
`not_requested`	L’appel était une récupération Lite : aucun actionnariat n’a été demandé.
`delivered`	Le registre a fourni les données d’actionnariat, et le niveau indiqué dans `registry_tier_delivered` est celui que vous payez.
`not_held`	Le registre de l’actionnariat a répondu mais ne répertorie pas cette entreprise : il n’a donc aucun enregistrement d’actionnariat à fournir. L’entreprise a été trouvée par une autre source de registre du pays. Le profil Lite est alors livré et facturé à la place, avec `registry_data.ownership_error: "company_not_found"`.
`unavailable`	Les données d’actionnariat n’ont pas été fournies pour une autre raison : l’enregistrement détenu par le registre ne nomme aucun propriétaire, ou le registre n’a pas renvoyé la section d’actionnariat, ou il n’a pas pu être interrogé. `registry_data.ownership_error` indique laquelle. Le profil Lite est alors livré et facturé à la place.
`pending`	La section d’actionnariat n’a pas encore été récupérée auprès du registre. Rien n’est facturé et `registry_tier_delivered` vaut `null` tant qu’elle ne l’a pas été.

not_held et unavailable sont tous deux livrés et facturés comme Lite, mais ne correspondent pas au même constat : not_held signifie que la source d’actionnariat ne couvre pas l’entreprise, c’est-à-dire une lacune de couverture, alors que unavailable signifie que les données n’ont pas été fournies, à cause d’une panne ou d’une section laissée vide par le registre. registry_data.ownership_error précise la raison. Les sélections qui signalaient auparavant unavailable parce que le registre d’actionnariat ne répertoriait pas l’entreprise signalent désormais not_held. Si vous traitez le statut de manière conditionnelle, traitez les deux comme une même livraison Lite. Deux de ses valeurs ont des sens différents et ne doivent pas être lues comme le même constat :

`ownership_error`	Signification
`no_owners_on_record`	Le registre a répondu à la section d’actionnariat et elle ne nomme aucun propriétaire. L’entreprise n’a pas de table de capitalisation enregistrée auprès de ce registre.
`ownership_section_unavailable`	Le registre n’a pas renvoyé la section d’actionnariat, donc rien n’a été livré pour elle. La liste est absente, et non vide : elle ne dit rien sur la propriété de l’entreprise.

Une section que le registre n’a pas renvoyée est également consignée de façon structurée, sous registry_data.section_errors, indexée par section (officers, shareholders, group_structure) avec le statut indiqué par la réponse du registre :

{
  "section_errors": {
    "shareholders": {
      "status_code": 404
    }
  }
}

section_errors décrit la réponse que vous détenez, et non l’historique qui y a mené. Une section non renvoyée lors de la première requête, puis fournie lors d’un passage ultérieur (voir la récupération asynchrone ci-dessous), perd son entrée. Ainsi, registry_ownership_status, ownership_error et section_errors concordent toujours : une section delivered n’a jamais d’entrée, et no_owners_on_record n’est jamais accompagné d’une entrée pour shareholders. Une section n’est jamais livrée en partie : si le registre fournit la première page d’une liste puis échoue à en fournir une page ultérieure, la récupération n’est pas terminée lors de cette tentative. Une récupération pending est alors réessayée lors de son prochain passage, et une nouvelle requête reçoit l’erreur de registre indisponible. Une liste officers ou d’actionnaires livrée est donc toujours la liste complète détenue par le registre. Traitez une section figurant dans section_errors comme une donnée qui n’a jamais été livrée, et jamais comme un résultat vide : une liste officers ou d’actionnaires vide accompagnée d’une entrée section_errors pour cette section ne dit rien sur l’entreprise.

Actionnariat récupéré de manière asynchrone

Certains registres sont interrogés à la demande : la première requête portant sur une entreprise que la source n’a jamais consultée ne renvoie aucune section d’actionnariat pendant qu’elle est récupérée, et les données arrivent en quelques minutes. Signaler cela comme « aucun actionnariat enregistré » sous-estimerait une entreprise qui possède bel et bien des actionnaires. La requête revient donc avec le statut pending. Pendant qu’une récupération est pending, fetch_status vaut également pending et la réponse a le statut 202 Accepted. Didit réessaie la section de son propre chef et termine la récupération sans aucun nouvel appel de votre part :

une fois les données d’actionnariat arrivées, les actionnaires et les bénéficiaires effectifs apparaissent sur la vérification enregistrée, registry_tier_delivered prend la valeur du niveau fourni, et l’usage est facturé à ce niveau ;
si la section est toujours vide à la fin de la fenêtre de nouvelles tentatives, le statut devient unavailable et la requête est livrée et facturée comme Lite.

Conservez le request_id et interrogez GET /v3/session/{request_id}/decision/ jusqu’à ce que registry_checks[0].company.fetch_status vaille resolved. Ne relancez pas la demande de récupération tant qu’elle est pending : chaque nouveau POST est une requête distincte, facturée séparément. Utilisez POST /v3/kyb/search/ pour trouver des entreprises candidates. La recherche ne crée pas de vérification enregistrée. L’entrée tier de la recherche détermine la chaîne qu’elle interroge. Voir niveau de recherche. Les recherches dans les registres peuvent prendre environ 90 secondes. Envoyez webhook_url si vous voulez que Didit vous réponde immédiatement et envoie une notification à votre URL dès que les candidats sont prêts. Le callback de recherche n’est pas signé, délibérément : vous n’avez donc pas besoin de configurer un secret partagé pour cette notification légère. Utilisez POST /v3/kyb/select/, POST /v3/kyb/shareholders/ ou POST /v3/kyb/ubo/ avec le kyb_response_id renvoyé pour récupérer le profil au niveau dont vous avez besoin. La récupération est facturable et enregistre le résultat sous forme de Manual Check dans la Business Console.

Déroulement type

Recherchez par nom d’entreprise, numéro d’immatriculation et pays, sur le tier que vous comptez acheter (basic est la chaîne Lite par défaut ; shareholders et ubo recherchent dans la chaîne de ce niveau).
Si search_resolved=false, attendez le callback webhook_url facultatif au lieu d’interroger le serveur.
Présentez les candidats renvoyés à votre opérateur ou à votre client.
Récupérez le kyb_response_id correspondant au niveau dont vous avez besoin (select pour Lite, shareholders ou ubo).
Conservez le request_id renvoyé et utilisez-le pour récupérer le résultat enregistré de la vérification d’entreprise.

Rappel de recherche

Lorsque le fournisseur indique à Didit que la recherche est terminée, Didit envoie une requête POST vers votre webhook_url :

{
  "event_id": "7f5a1c93-6a44-4f0e-9f2b-3d8a1c6f2e91",
  "event_type": "kyb.registry_search.resolved",
  "request_id": "b5ef9df5-bd9e-4d61-bbe5-5eb7a8fb6f85",
  "vendor_data": "business-123",
  "metadata": {
    "source": "onboarding"
  },
  "search_status": "resolved",
  "search_resolved": true,
  "kyb_registry": {
    "companies": [
      {
        "kyb_response_id": "kyb_resp_123",
        "name": "TESCO PLC",
        "registration_number": "00445790",
        "status": "active",
        "type": "Public Limited Company",
        "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA",
        "risk_level": null,
        "fetch_status": "pending"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "per_page": 25
    },
    "search_status": "resolved",
    "search_resolved": true
  },
  "timestamp": 1767225600,
  "created_at": 1767225600
}

Traitez ce rappel comme une notification de livraison. Utilisez le kyb_response_id renvoyé avec POST /v3/kyb/select/, POST /v3/kyb/shareholders/ ou POST /v3/kyb/ubo/ pour lancer la récupération facturable du profil du registre.

Dernière modification le 7 novembre 2026

​Endpoints et facturation

​Statut de l’actionnariat

​Actionnariat récupéré de manière asynchrone

​Déroulement type

​Rappel de recherche

Endpoints et facturation

Statut de l’actionnariat

Actionnariat récupéré de manière asynchrone

Déroulement type

Rappel de recherche