--- title: "Rechercher des entreprises" method: POST path: "/companies/find" tags: ["Entreprises"] --- # Rechercher des entreprises `POST /companies/find` ## Request - Base URL: `https://api.basile.cc` - URL: `https://api.basile.cc/companies/find` - Auth: API key in header `Authorization` Recherche de sociétés sur les trois sources (registre, LinkedIn, GMB). **Pour compter sans extraire ni être facturé**, envoyer `countOnly: true` (ou `limit: 0`) : la réponse contient `total` et un `leads` vide. Sinon, chaque enregistrement renvoyé coûte 1 crédit. Les résultats rattachés au registre portent `data.procedure_statut` : le statut de procédure collective calculé sur les jugements publiés au BODACC (`code`, `depuis`, `tribunal`, `organes`, `plan_duree_ans`, `source`…), absent quand la société n'a jamais connu de procédure. C'est `code` qui distingue un plan (`plan_redressement`, `plan_sauvegarde`) d'une période d'observation (`redressement`, `sauvegarde`) : aucun filtre ne le fait. ## Request body - FindCompaniesRequest - `limit` integer: Taille de page (défaut 100). Cap = **1000** en mode normal ; **5000** en mode `idsOnly` côté `/people/find` (companies reste à 1000). `0` = **compter seulement** (équivalent à `countOnly: true`, gratuit). ⚠️ `1` n'est PAS un mode de comptage : cela renvoie 1 enregistrement, donc 1 crédit — utiliser `countOnly`. - `countOnly` boolean: Si `true`, `/find` ne renvoie que le `total` avec un tableau `leads` **vide** : c'est le mode de comptage **gratuit** (aucun enregistrement renvoyé, donc **aucun crédit débité**), quel que soit le nombre de résultats. Équivalent à `limit: 0`. À utiliser systématiquement pour cadrer un volume avant d'extraire. - `paginationToken` string: Curseur opaque renvoyé dans `pagination.nextToken` pour la page suivante. - `idsOnly` boolean: Si `true`, `/find` ne renvoie que `{ _id, source }` (champ `data` vide), sans enrichissement par ligne — beaucoup plus léger et rapide pour collecter les IDs d'un grand résultat. Permet `limit` jusqu'à 5000 côté `/people/find`. À utiliser quand on a besoin de la liste d'IDs avant un export par `{ ids }` ou un ré-enrichissement par lots. Pour un simple CSV, préférer `/export` par `filters` (export streamé, jusqu'à la limite par export du plan). - `filters` FindCompaniesFilters: Filtres de recherche d'entreprises. Trois sources : **Legal** (registre), **LKI** (LinkedIn), **GMB** (Google My Business). - `name` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `activity` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `naf_code` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `headquarters_department_code` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `headquarters_region_code` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `headquarters_postal_code` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `headquarters_city` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `headquarters_country_code` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `legal_form` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `legal_category` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `siren` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `headcount_min` integer: Effectif minimum (Legal + LKI). - `headcount_max` integer: Effectif maximum (Legal + LKI). - `capital_min` number: Legal-only. Capital social min (€). - `capital_max` number: Legal-only. Capital social max (€). - `company_ceased` boolean: false = actives uniquement (recommandé). true = cessées. - `publishable` boolean: Legal-only. Diffusable. - `with_procedure` boolean: Legal-only (restreint la recherche au registre). true = la société a connu une procédure collective, en cours ou clôturée, d'après les jugements publiés au BODACC (546 592 sociétés). false = aucune procédure connue, ni en cours ni clôturée. - `procedure_open` boolean: Legal-only (restreint la recherche au registre). true = procédure en cours, plans de redressement et de sauvegarde en cours d'exécution compris (168 250 sociétés, dont 150 544 encore actives). false = écarte les procédures en cours : garde les sociétés sans procédure et celles dont la procédure est clôturée. - `procedure_type` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `idcc` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `created_since_months` number: Legal-only. Entreprises créées dans les N DERNIERS MOIS (ex. 3). Plus précis que creation_date_*, qui raisonne en années civiles. - `creation_date_min` string: Legal-only. ANNÉE de création min (2015 ou '2015'). ⚠️ JAMAIS de date complète ('2015-03-01') : elle serait SILENCIEUSEMENT ignorée (résultats non filtrés). - `creation_date_max` string: Legal-only. ANNÉE de création max (année seule, pas de date complète). - `industry_main` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `company_type` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `domain` IncludeExcludeFilter: Filtre texte. `include` = OR entre les valeurs (au moins une matche). `exclude` = exclut toute valeur qui matche. Les deux peuvent être combinés. Plusieurs filtres distincts se combinent en **ET**. - `include` string[] - `exclude` string[] - `followers_min` integer: LKI-only. Followers LinkedIn min. - `followers_max` integer: LKI-only. Followers LinkedIn max. - `rating_min` number: GMB-only. Note Google min (0-5). - `rating_max` number: GMB-only. Note Google max. - `reviews_min` integer: GMB-only. Nb d'avis min. - `reviews_max` integer: GMB-only. Nb d'avis max. - `is_opening` boolean: GMB-only. Ouvert le dimanche. - `source` 'Legal' | 'LKI' | 'GMB': Forcer une seule source. - `with_legal_data` boolean: Filtre ET, PAS un choix de source : garde les entreprises qui ont AUSSI une fiche au registre. Les trois sources restent interrogées, chacune filtrée. Pour ne lire que le registre, utiliser source=Legal. - `with_linkedin_page` boolean: Filtre ET, PAS un choix de source : garde les entreprises qui ont AUSSI une page LinkedIn. Pour ne lire que LinkedIn, utiliser source=LKI. - `with_email` boolean: Filtre ET : garde les entreprises pour lesquelles nous avons une adresse email d'entreprise, relevée sur leur site. - `with_phone` boolean: Filtre ET : garde les entreprises pour lesquelles nous avons un numéro de téléphone d'entreprise (standard de la fiche Google Maps, ou numéro affiché sur le site) ; ce n'est pas le mobile d'une personne. La source LinkedIn ne répond pas encore à ce filtre et renvoie 0 : résultats incomplets, jamais faux. ## Response `200` Résultats paginés. - PaginatedCompanies - `success` boolean - `total` integer: Total de résultats (somme des sources, sans dédup cross-source). - `leads` MergedItem[] - `_id` string - `source` 'Legal' | 'LKI' | 'GMB' - `matchQuality` 'exact' | 'employer_approximate' | 'employer_former' | 'name_only' | 'role_approximate' | 'holding_officer' | 'registry_mandate' | 'registry_holding' | 'linkedin_title' | 'registry_mandate_ended': `/people/find` par clé d'API, recherche récupérée après un zéro : comment la fiche répond. `exact` et `employer_approximate` (la bonne société, nom ou SIREN retrouvé) sont facturées ; `employer_former`, `name_only`, `role_approximate` (intitulé de dirigeant LinkedIn pour un mandat introuvable) et `holding_officer` (dirigeant de la holding qui dirige la société) sont offertes. Dirigeants d'un SIREN (`siren` + `mandate_role`) : `registry_mandate` (mandat lu au registre, fiche rattachée à une autre société) et `registry_holding` (dirigeant de la holding qui tient le mandat, chaîne dans `mandate.via`) sont facturées ; `linkedin_title` (profil LinkedIn à titre de dirigeant, aucun dirigeant en poste au registre) et `registry_mandate_ended` (mandat terminé au registre) sont offertes. Absent sur toute autre recherche. - `mandate` MandatDirigeant: Dirigeants d'un SIREN par clé d'API : le mandat que la personne exerce DANS LA SOCIÉTÉ CHERCHÉE, quelle que soit la société à laquelle sa fiche est rattachée. Absent sur toute autre recherche. - `siren` string: SIREN de la société cherchée. - `company_name` string - `role` string: Mandat dans la société cherchée (« Président »), directement ou par la chaîne via. - `is_current` boolean - `start_at` string: AAAA-MM-JJ, quand le registre la donne. - `end_at` string: AAAA-MM-JJ, quand le registre la donne. - `label` string: Libellé prêt à afficher. - `via` ViaHolding: Holding intermédiaire d'une chaîne de direction, de la société cherchée vers le haut. - `siren` string - `name` string - `role` string: Mandat que CETTE holding exerce dans la société juste en dessous d'elle. - `via` ViaHolding (recursive) - `person_role` string: Rôle de la personne dans la dernière holding de la chaîne (« Gérant »). - `card_siren` string: Société à laquelle la fiche est rattachée, quand ce n'est pas la société cherchée. - `card_role` string: Titre porté par la fiche, quand il diffère du mandat dans la société cherchée. - `unconfirmed` boolean: Vrai quand le mandat n'est lu que sur la fiche rattachée, sans confirmation au registre des mandats (ces fiches viennent après les mandats confirmés). - `data` object: Champs bruts de la source (varie selon `source`). - `pagination` object: Présent uniquement s'il reste une page. - `nextToken` string - `meta` SearchMeta - `sources` string[]: Sources réellement interrogées. - `noticeCode` string: people_overcount, sources_split, siren_no_linkedin_company, gmb_filter_dropped, sources_conflict… - `notice` string - `countCapNotice` string - `warnings` SearchWarning[]: Présent seulement quand il y a quelque chose à dire. - `code` string: Code stable. Personnes dans une société (employeur ou SIREN) à zéro : `company_role_absent` (société connue, personne avec ce rôle ou ce nom), `company_without_people` (société connue, aucune personne rattachée chez Basile), `person_at_other_company` (la personne est connue ailleurs), `company_not_found` (aucune société sous ce nom ou ce SIREN, noms proches proposés). Récupérations : `employer_approximate`, `employer_former`, `employer_not_matched`, `role_approximate`, `holding_officers`. Activité : `activity_translated`, `activity_unreadable`, `activity_exclusion_ignored`. Dirigeants d'un SIREN : `siren_mandate_elsewhere`, `siren_via_holding`, `siren_holding_without_person`, `siren_linkedin_fallback`, `siren_mandates_ended`, `siren_no_known_mandate`, `siren_too_many`, `mandate_role_unknown` (un zéro qu'ils expliquent n'est pas complété par les récupérations par société). École et langues : `filter_values_truncated`, `filter_values_ignored`. Domaine (entreprises) : `domain_invalid`, `domain_label`, `domain_any`, `domain_parent`. - `message` string: Explication en anglais. - `messageFr` string: La même en français, quand elle existe. - `filters` string[]: Clés de filtre en cause. - `blocking` boolean: Vrai quand ce constat suffit à rendre 0 résultat. - `details` object: Chiffres et noms propres au code : `knownEmployees`, `knownOfficers`, `siren`, `linkedinPage`, `inLegalRegistry`, `currentEmployer` (seulement si sûr), `suggestions` (noms proches et SIREN), `ceasedCompanies`, `activeHomonyms`, `matchedEmployers` et `sirens` (à relancer pour paginer une récupération), `truncated`. Dirigeants : `sirens`, `holdings`, `not_tried`, `other_current_roles`, `values`, `max`. École et langues : `side`, `max`, `received`, `dropped`, `minChars`, `ignored`. ## Other responses - `400`: Aucun filtre effectif. Une clé d'API doit poser au moins un filtre qui restreint réellement le résultat. Ne comptent pas : filters vide, {"include":[]}, null, "", une clé inconnue, et source seul. - `401`: Clé API absente ou invalide. - `402`: La pagination (page > 1) requiert un abonnement actif. - `403`: Clé réservée à l'enrichissement (compte à crédits sans forfait API) utilisée hors de /enrichment. - `429`: Trop de requêtes. Respecter le header `Retry-After` (secondes). Plafonds par forfait (requêtes par seconde, par minute, par jour, remise à zéro à minuit UTC) : api 5, 100, 2 000 ; agency 100, 3 000, 5 000 ; custom 100, 3 000, 50 000. `error` vaut `daily_limit_exceeded` quand le plafond du jour est atteint, `rate_limit_exceeded` pour la seconde ou la minute. --- [API](https://skmtc.dev/basile/apis/basile-api.md) · [All operations](https://skmtc.dev/basile/apis/basile-api/llms.txt) · [OpenAPI document](https://skmtc.dev/basile/apis/basile-api/revisions/f260fbfcc5eb?raw)