--- title: "Rechercher des personnes" method: POST path: "/people/find" tags: ["Personnes"] --- # Rechercher des personnes `POST /people/find` ## Request - Base URL: `https://api.basile.cc` - URL: `https://api.basile.cc/people/find` - Auth: API key in header `Authorization` Recherche de contacts (dirigeants légaux et/ou profils LinkedIn). Renvoie un total et une page de résultats. **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. La page 1 est accessible sans abonnement ; la pagination (page > 1) requiert un abonnement actif. ## Request body - FindPeopleRequest - `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` FindPeopleFilters: Filtres de recherche de personnes. Deux sources : **Legal** (registre) et **LKI** (LinkedIn). Activer un filtre Legal-only exclut LinkedIn, et inversement (voir descriptions). - `result_full_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[] - `result_first_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[] - `result_last_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[] - `result_role` 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[] - `company_headcount` RangeFilter: Filtre numérique (bornes). Tous les opérateurs sont optionnels. - `>` number - `>=` number - `<` number - `<=` number - `employer` 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[] - `result_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[] - `result_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[] - `mandate_role` 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[] - `legal_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[] - `nationality` 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[] - `nationality_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[] - `result_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[] - `result_is_legal_entity` boolean: Legal-only. La 'personne' est une personne morale. - `result_is_current` boolean: Legal-only. Mandat actuel uniquement. - `result_age` RangeFilter: Filtre numérique (bornes). Tous les opérateurs sont optionnels. - `>` number - `>=` number - `<` number - `<=` number - `result_total_companies_count` RangeFilter: Filtre numérique (bornes). Tous les opérateurs sont optionnels. - `>` number - `>=` number - `<` number - `<=` number - `current_seniority` 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[] - `current_job_functions` 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[] - `skills` 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[] - `languages` 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[] - `education` 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[] - `past_title` 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[] - `past_employer` 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[] - `connection_count` RangeFilter: Filtre numérique (bornes). Tous les opérateurs sont optionnels. - `>` number - `>=` number - `<` number - `<=` number - `current_tenure_years` RangeFilter: Filtre numérique (bornes). Tous les opérateurs sont optionnels. - `>` number - `>=` number - `<` number - `<=` number - `linkedin_url` 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[] - `source` 'Legal' | 'LKI': Forcer une seule source. - `with_legal_data` boolean: Restreint la recherche à la source Registre (équivaut à source=Legal). Attention : sur /companies/find, le filtre du même nom ne restreint PAS la source, c'est un filtre ET. - `with_linkedin_profile` boolean: Restreint la recherche à la source LinkedIn (équivaut à source=LKI). Si les deux bascules sont vraies, with_legal_data l'emporte. - `hide_legal_entities` boolean: Masque les personnes morales (recommandé : true) sans exclure LinkedIn. - `employerFallback` boolean: Recherche de personnes dans une société (`employer` ou `siren`) par clé d'API : `false` garde le comportement strict quand la recherche telle quelle rend zéro (aucune récupération : nom nettoyé, SIREN du registre, page au nom de la société, holding, intitulés de dirigeant). Les avertissements de `meta.warnings` restent. - `registryMandates` boolean: Dirigeants d'un SIREN par clé d'API (`siren` + `mandate_role`) : `false` garde le comportement d'avant, seules les fiches RATTACHÉES au SIREN (ni mandats lus au registre, ni holdings, ni repli LinkedIn). ## Response `200` Résultats paginés. - PaginatedPeople - `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)