Fichier de prospection : le constituer ou l'acheter

Compter un ciblage avant de l'extraire

Le comptage répond à la seule question qui vaille : combien de lignes correspondent à votre filtre, et non combien la base en contient. Il est gratuit sur les trois voies, ne débite aucun crédit et n'entame pas le quota d'export. C'est donc le geste à répéter autant de fois que nécessaire, jusqu'à ce que le volume et le message tiennent ensemble.

Dans la plateforme, pas à pas

1. Ouvrez la recherche et choisissez l'onglet « Entreprises » ou « Personnes » selon ce que doivent être vos lignes. Une ligne « entreprise » et une ligne « contact » ne se filtrent pas avec les mêmes champs.
2. Dans le panneau « Filtres » à gauche, posez d'abord « Activité » : ce champ unifie le code NAF, la catégorie Google et le secteur LinkedIn, et c'est le plus discriminant. Puis « Localisation » (ville, département ou région), puis « Employés » si la taille compte.
3. Sur la recherche entreprises, vérifiez que « Entreprises actives uniquement » est bien active. Elle l'est par défaut, et c'est elle qui écarte les immatriculations cessées. La recherche personnes n'a pas cette bascule.
4. En haut du panneau, le bloc « Avec : » regroupe les bascules de présence de champ. Sur les entreprises il y en a quatre : « Données légales », « Page LinkedIn », « Email », « Téléphone ». Sur les personnes il n'y en a qu'une, « Profil LinkedIn ». Activez celle du champ sans lequel votre fichier ne sert à rien. Ce ne sont pas des sélecteurs de source : chacune exclut les fiches où le champ manque, donc chaque bascule ajoutée fait baisser le compte.
5. Lisez le compteur au-dessus des résultats : « N résultats ». Sur une recherche d'entreprises, un second compteur donne le nombre d'établissements, presque toujours supérieur (une enseigne compte pour une entreprise et pour des dizaines de points de vente).
6. Recommencez en desserrant ou en resserrant un critère à la fois. Tant que vous n'exportez pas et n'ajoutez rien à une liste, rien n'est débité.

Trois réserves à connaître. D'abord, le filtre « Employés » exclut d'office les entreprises dont l'effectif est inconnu, et l'effectif n'est renseigné que pour environ une entreprise sur quinze (l'infobulle du champ le dit) : c'est le filtre qui fait chuter un compte le plus brutalement, souvent sans que ce soit voulu. Ensuite, la bascule « Téléphone » ne retient que les fiches entreprises qui portent le drapeau correspondant, posé aujourd'hui sur 815 225 d'entre elles, et « Email » sur 180 278 : le compte qui en sort est donc petit par construction, vérifiez-le avant de bâtir une campagne dessus. Enfin, au-delà de 2 000 résultats, le total d'une recherche entreprises est la somme des trois index avant déduplication, donc surestimé, alors que le fichier exporté, lui, est dédupliqué. Prenez ce chiffre comme un ordre de grandeur et resserrez jusqu'à ce qu'il redescende.

Par l'API : POST /companies/find

{
  "filters": {
    "activity": { "include": ["plomberie_chauffage_clim"] },
    "headquarters_department_code": { "include": ["69"] },
    "company_ceased": false,
    "with_phone": true
  },
  "countOnly": true
}

La réponse porte `total` (le nombre de lignes que rendrait ce filtre), `leads: []` (vide, puisque rien n'est renvoyé et donc rien n'est facturé) et `meta.sources` (les index qui ont effectivement contribué). Sur les entreprises s'ajoutent `establishmentsTotal`, le nombre d'établissements Google derrière les sociétés dédupliquées, et `totalEstimated: true` quand le total dépasse 2 000 et n'est donc plus exact mais une somme cross-sources avant déduplication. La même requête sur `/people/find` fonctionne à l'identique, avec les filtres personnes (`activity`, `result_role`, `region`, `current_seniority`, `with_linkedin_profile`, etc.).

Le piège coûteux : `limit: 1` n'est pas un mode de comptage, cela renvoie un enregistrement et facture un crédit. Seuls `countOnly: true` ou `limit: 0` comptent sans rien débiter. Deuxième point, `countOnly` est aussi le seul moyen d'obtenir un total NON PLAFONNÉ par clé d'API : un `/find` normal borne son total à 100 000 et pose alors `meta.countCapNotice`. Non plafonné ne veut pas dire exact pour autant : sur les entreprises, au-delà de 2 000, le total reste une somme cross-sources marquée `totalEstimated: true`. La clé se passe dans l'en-tête `Authorization`, en clair, sans préfixe `Bearer`. Enfin, une clé d'API doit poser au moins un filtre effectif : un `filters: {}` est refusé en 400 (« At least one filter is required »).

Le détail des champs, des filtres et des codes de réponse est dans la documentation de l'API.

Avec Claude, en langage courant

Combien y a-t-il d'entreprises de plomberie et chauffage encore en activité dans le Rhône, et combien d'entre elles ont un numéro de téléphone ?

Claude enchaîne basile_activity_suggest puis basile_count.

Claude commence par `basile_activity_suggest` pour convertir « plomberie et chauffage » en identifiant de concept, puis appelle `basile_count` deux fois : une fois sans la bascule téléphone, une fois avec `with_phone: true`. L'écart entre les deux est exactement la question posée plus haut dans ce chapitre, celle du taux de remplissage du champ décisif. `basile_count` est gratuit et son total n'est pas plafonné, contrairement à celui des outils de recherche.

Extraire le fichier en CSV

Une fois le compte accepté, l'extraction rend un CSV large (79 colonnes sur les personnes) qui contient la donnée déjà présente en base : coordonnées relevées sur le site et sur la fiche Google (`crawled_emails`, `crawled_phones`, `gmb_phone`, `gmb_website`), identité légale (`legal_siren`, `legal_capital`, `legal_tranche_effectif`), technologies du site (`tech_stack`) et indicateurs de remplissage (`has_crawled_email`, `has_gmb_match`, `fill_score`). Deux colonnes font exception : `person_email` et `person_phone`, les coordonnées nominatives, ne sont remplies que pour les contacts que vous avez déjà révélés, l'enrichissement étant une opération séparée, payante, et hors de portée d'une clé d'API. Un petit volume sort en flux, dans la réponse même de la requête. Un gros volume passe par un export asynchrone, qui construit le fichier de son côté et vous rend un lien de téléchargement.

Dans la plateforme, pas à pas

1. Depuis les résultats, choisissez la portée. « Sélectionner la page » ne prend que l'écran courant, « Sélectionner tous les résultats » prend l'ensemble du ciblage, et « Sélectionner une tranche… » demande deux rangs (« Du résultat n° » 1 « Au résultat n° » 500, puis 501 à 1500 la fois suivante), ce qui sert à découper un gros fichier en lots traitables.
2. Cliquez sur « Exporter ».
3. Sur une recherche d'entreprises, la fenêtre « Exporter en CSV » demande le « Format d'export » : « Par entreprise » (une ligne par entreprise, dédupliqué) ou « Par point de vente » (une ligne par établissement Google). Le second est ce que produirait une extraction Google Maps, et il rend beaucoup plus de lignes pour les enseignes à réseau.
4. Sur une recherche de personnes, la fenêtre propose « Contacts à inclure » : « Tout », « Avec email », « Avec téléphone », « Avec email et téléphone ». Attention, ces trois derniers ne portent que sur les coordonnées que vous avez déjà révélées dans cette recherche, et restent inactifs tant que vous n'avez rien enrichi.
5. Le bouton porte le nombre de lignes réel : « Exporter N lignes ». Cliquez.
6. L'export part en tâche de fond. Sa progression s'affiche dans le menu « Exports » de la barre de navigation, et le téléchargement se déclenche à la fin. Le fichier reste retéléchargeable depuis ce menu pendant sept jours, sans être refacturé.

Si votre forfait plafonne le nombre de lignes par export, la fenêtre l'annonce (« Export limité à N résultats pour votre forfait actuel ») et le fichier s'arrête à ce plafond. C'est là que la sélection par tranche prend son sens : plutôt que d'élargir le filtre, découpez le même ciblage en tranches de rangs successives, ou en sous-segments géographiques, et exportez-les l'un après l'autre.

Par l'API : POST /exports

{
  "source": "companies",
  "mode": "companies",
  "filters": {
    "activity": { "include": ["plomberie_chauffage_clim"] },
    "headquarters_department_code": { "include": ["69"] },
    "company_ceased": false,
    "with_phone": true
  },
  "filename": "plomberie-rhone-2026.csv"
}

La création répond en 202 avec `job.id`, `job.status` (« queued ») et `job.filename`. Interrogez ensuite `GET /exports/{jobId}` : la réponse porte `status` (« queued », « running », « done », « partial », « failed »), `rowCount` (les lignes déjà écrites), `truncated`, `quotaReached` et `expiresAt`. Le travail démarre de lui-même quelques secondes après sa création, donc l'interrogation périodique suffit ; `GET /exports/{jobId}/stream` (SSE) le lance immédiatement et en suit la progression ligne à ligne. Quand `status` vaut « done » ou « partial », `GET /exports/{jobId}/download` répond par une redirection 302 vers un lien signé (suivez la redirection, avec `curl -L` par exemple). Tant que le fichier n'est pas prêt, cette route répond 409 « not_ready » ; passé sept jours, 410 « expired ». `GET /exports` liste vos exports récents.

Pour un petit volume, l'export direct en flux évite le va-et-vient : `POST /people/export` ou `POST /companies/export` prend le même corps que `/find`, plus `ids` pour n'exporter qu'une sélection d'identifiants, plus `contacts` (« all », « email », « phone », « both ») côté personnes et `mode` (« companies » ou « locations ») côté entreprises. Le CSV arrive dans la réponse, avec les en-têtes `X-Export-Max-Rows` (le plafond de votre forfait) et `X-Export-Capped: true` quand il reste des résultats au-delà. Ce chemin garde la connexion ouverte pendant toute la marche : au-delà de quelques milliers de lignes, préférez `/exports`, qui construit le fichier hors du fil de la requête et survit à une coupure. Trois règles s'appliquent aux deux : une clé d'API doit poser au moins un filtre effectif (sinon 400), un quota mensuel épuisé répond 402 « export_quota_exhausted » (et non 429, ce n'est pas une limite de débit), et le séparateur d'un export par clé d'API est toujours la virgule, quel que soit le réglage du compte, pour qu'une intégration ne voie jamais son format changer sans prévenir.

Le détail des champs, des filtres et des codes de réponse est dans la documentation de l'API.

Avec Claude, en langage courant

Exporte-moi en CSV les entreprises de plomberie et chauffage encore en activité dans le Rhône qui ont un numéro de téléphone.

Claude enchaîne basile_count puis basile_export.

`basile_export` rend le CSV directement dans la conversation, ce qui le limite à 500 lignes : une conversation ne peut pas absorber un gros fichier. Au-delà, Claude vous dira de resserrer le ciblage, ou de lancer l'export depuis la plateforme ou par l'API, qui rendent un fichier téléchargeable. Sur les entreprises, `mode: "locations"` sort une ligne par point de vente, à utiliser quand `establishmentsTotal` dépasse nettement `total`. L'export consomme le quota du forfait, d'où la consigne de compter d'abord.

Enregistrer le ciblage dans une liste et l'alimenter par filtre

Un fichier de prospection vit plusieurs semaines, et le ciblage qui l'a produit vaut plus que le fichier lui-même. Une liste garde ce ciblage : on l'alimente par filtre, on la recompte, on la réexporte autant de fois qu'on veut sans refaire le travail de segmentation. La facturation se déplace en conséquence : l'ajout à une liste coûte un crédit par nouvel enregistrement, et l'export de la liste est ensuite gratuit et illimité.

Dans la plateforme, pas à pas

1. Depuis les résultats, sélectionnez la portée voulue (la page, tous les résultats, ou une tranche de rangs) et cliquez sur « Ajouter à une liste ».
2. Dans la fenêtre, saisissez un nom sous « Nouvelle liste » et cliquez « Créer », ou choisissez une liste existante dans la recherche en dessous. Les doublons sont ignorés automatiquement, et un enregistrement déjà présent ne recoûte rien.
3. Une confirmation annonce le coût avant d'engager quoi que ce soit : le nombre de résultats concernés, le nombre de crédits que cela consommera au maximum, et vos crédits restants pour le mois. Si vos crédits ne couvrent pas toute la sélection, elle propose d'ajouter seulement ce qui tient.
4. L'ajout tourne en tâche de fond, avec sa progression dans le menu des tâches. Vous pouvez continuer à chercher pendant ce temps.
5. Retrouvez la liste dans « Mes listes ». La colonne « Prêt pour l'export » indique combien de ses enregistrements sont préparés pour l'export ; le bouton « Synchroniser pour l'export » relance la préparation de ceux qui manquent encore.
6. Dans la liste, la barre d'outils propose un champ « Rechercher des leads… » et trois menus, « Trier », « Filtrer » et « Colonnes », pour restreindre ce que le fichier contiendra, puis « Exporter » sort le CSV correspondant à ce que vous voyez à l'écran.

Le compteur « Prêt pour l'export » n'est pas décoratif. Après une mise à jour de la base, les données d'export des membres de vos listes sont recalculées, et le compteur repart en dessous du total le temps que cela rattrape. Vos listes restent utilisables pendant ce temps, mais un export lancé trop tôt sera incomplet : attendez que le compteur ait rejoint le total, ou forcez la préparation avec « Synchroniser pour l'export ». Autre point pratique : si une recherche ou un filtre est actif dans la liste, l'envoi de la liste entière n'en tient pas compte, il faut cocher les lignes voulues.

Par l'API : POST /lists/{listId}/items/by-filter

{
  "filters": {
    "activity": { "include": ["plomberie_chauffage_clim"] },
    "headquarters_department_code": { "include": ["69"] },
    "company_ceased": false,
    "with_phone": true
  },
  "confirm": true
}

La liste se crée d'abord par `POST /lists` avec `{ "name": "Plomberie Rhône 69", "type": "companies" }` (ou `"people"`), dont la réponse porte l'identifiant à replacer dans le chemin. L'ajout par filtre sans `confirm` répond `needsConfirmation: true` avec `total` (le nombre de résultats correspondants), `wouldAdd`, `willAdd` (ce qui tient dans vos crédits restants), `remaining` et `monthlyLimit` : c'est un devis, rien n'est engagé. Renvoyez la même requête avec `confirm: true` et la réponse devient `added`, `charged`, `itemCount` (la taille de la liste après ajout), `totalMatched`, `truncated` et `quotaReached`.

Deux variantes utiles. Pour un très gros ciblage, `POST /lists/{listId}/add-jobs` avec `{ "selectionType": "filter", "filters": { … }, "selectedCount": 12000 }` crée un travail durable et répond 202 avec `job.id` ; il faut ensuite ouvrir `GET /lists/{listId}/add-jobs/{jobId}/stream`, qui pilote réellement la marche, et `GET /lists/{listId}/add-jobs/{jobId}` sert de repli pour en lire l'état. Un travail créé sans que ce flux soit ouvert reste en attente. L'ajout synchrone ci-dessus, lui, se suffit à lui-même, mais sa marche est bornée à cinquante pages : 250 000 enregistrements au maximum sur une liste de personnes (5 000 par page), 50 000 sur une liste d'entreprises (1 000 par page), en plus de la borne des crédits. Ensuite, `GET /lists/{listId}/export/count` donne le nombre de lignes exportables (et respecte une recherche ou un filtre passés en paramètres), et `POST /lists/{listId}/export` sort le CSV, gratuitement. Comme partout, une clé d'API doit poser au moins un filtre effectif : un `filters: {}` sur ces routes est refusé en 400, précisément pour qu'une liste ne puisse pas devenir une copie de l'index entier.

Le détail des champs, des filtres et des codes de réponse est dans la documentation de l'API.

Avec Claude, en langage courant

Le serveur MCP Basile n'expose que sept outils : basile_search_companies, basile_search_people, basile_count, basile_export, basile_get_entity, basile_suggest et basile_activity_suggest. Aucun ne crée de liste, n'y ajoute d'enregistrements ni ne l'exporte : le MCP se facture et se limite comme une clé d'API, et la gestion des listes n'en fait pas partie. Faites-le depuis la plateforme, ou par l'API avec une clé. Ce que Claude peut faire en revanche, c'est préparer le ciblage : trouver le bon identifiant d'activité, compter, vérifier le taux de remplissage du champ décisif, et vous rendre le corps JSON à envoyer.