API

L'API de Lead Empire

Chercher des entreprises, remplir des listes, enrichir, lancer des enchaînements et envoyer vers Mail Empire, depuis vos scripts et vos automatisations.

Démarrer#

Dans Lead Empire : Réglages → Compte et équipe → Clés API → Créer une nouvelle clé. Choisissez ce qu'elle peut faire (« Lecture seule » pour commencer) et, si vous voulez, une date d'expiration.
Copiez la clé (le_…) : elle ne s'affiche qu'une fois.
Appelez l'API avec l'en-tête Authorization: Bearer le_….

Dans les exemples, l'adresse de votre installation et la clé sont dans deux variables d'environnement :

Terminal

export LE_URL="https://votre-installation.example"   # l'adresse de VOTRE Lead Empire
export LE_CLE="le_..."                               # votre clé, jamais dans un fichier partagé

curl -s "$LE_URL/api/v1/me" -H "Authorization: Bearer $LE_CLE"

Toutes les réponses sont en JSON (UTF-8), les dates au format ISO 8601.

Les préréglages de clé#

Droit	Ce qu'il ouvre	Extension navigateur	Lecture seule	Automatisation
`me:read`	Lire le compte et la consommation des quotas	✓	✓	✓
`companies:read`	Lire les entreprises (recherche, fiches, contacts, signaux)		✓	✓
`companies:enrich`	Enrichir une entreprise (1 unité de quota)			✓
`companies:crawl`	Lire le site d'une entreprise (1 unité de quota)			✓
`lists:read`	Lire les listes et leur contenu		✓	✓
`lists:write`	Créer une liste, y ajouter ou en retirer des entreprises			✓
`lists:operate`	Enchaînements : composer, lancer (dépense selon les étapes), suivre, annuler			✓
`lists:export`	Envoyer une liste vers Mail Empire (données personnelles)
`lists:delete`	Supprimer une liste (les entreprises restent)
`review:decide`	Extension : revue qualité	✓
`crawl:worker`	Extension : lecture des sites par le poste	✓

Un quatrième préréglage, Accès complet, donne tous les droits, y compris ceux ajoutés plus tard : il est réservé à l'Admin du compte. « Sur mesure » permet de cocher les droits un par un. Les clés créées avant la version 1.153.0 gardent les droits qu'elles avaient.

Les routes#

Toutes sous $LE_URL/api/v1. Chaque route exige un droit, et la page correspondante doit être ouverte au compte de la clé.

Groupe	Routes	Droit
Compte	`GET` `/me`	`me:read`
Entreprises	`GET` `/companies/search` (registre national, en direct) · `GET` `/companies/local` (votre base, avec filtres) · `GET` `/companies/{siren}` · `GET` `/companies/{siren}/contacts`	`companies:read`
	`POST` `/companies/{siren}/enrich`	`companies:enrich`
	`POST` `/companies/{siren}/crawl`	`companies:crawl`
Signaux	`GET` `/signals`	`companies:read`
Listes	`GET` `/lists` · `GET` `/lists/{slug}`	`lists:read`
	`POST` `/lists` · `POST` `/lists/{slug}/companies` · `DELETE` `/lists/{slug}/companies`	`lists:write`
	`DELETE` `/lists/{slug}`	`lists:delete`
	`POST` `/lists/{slug}/export/mail-empire`	`lists:export`
Enchaînements	`GET` `/chain-actions` · `GET` `/chains` · `GET` `/lists/{slug}/chains/status`	`lists:read`
	`POST` `/chains` · `PUT` `/chains/{id}` · `DELETE` `/chains/{id}` · `POST` `/lists/{slug}/chains/launch` · `POST` `/chain-runs/{id}/cancel`	`lists:operate`

Les routes /review/… et /extcrawl/… servent à l'extension navigateur : elles ne sont pas faites pour vos scripts.

Ce que l'API ne laisse jamais sortir#

Les mêmes règles qu'à l'écran s'appliquent, sans paramètre pour les retirer : les adresses qui se sont opposées, les entreprises « Ne pas démarcher », les entreprises en diffusion partielle à l'INSEE (refusées avec 403 partial_diffusion), et les personnes dont le délai d'information est passé ne sortent pas.

Exemples#

Chercher dans votre base#

Les boulangeries du Rhône qui ont au moins une adresse e-mail :

Terminal

curl -s "$LE_URL/api/v1/companies/local?department=69&naf=10.71&has_email=1" \
  -H "Authorization: Bearer $LE_CLE"

Autres filtres : q, postal_code, city, category (PME, ETI, GE), employee_range, status, has_domain, signal_type, signal_since_days, sort, page, per_page (50 au plus).

Créer une liste et la remplir#

Terminal

curl -s -X POST "$LE_URL/api/v1/lists" \
  -H "Authorization: Bearer $LE_CLE" -H "Content-Type: application/json" \
  -d '{"name":"Prospects Lyon"}'

curl -s -X POST "$LE_URL/api/v1/lists/prospects-lyon/companies" \
  -H "Authorization: Bearer $LE_CLE" -H "Content-Type: application/json" \
  -d '{"sirens":["123456789","987654321"]}'   # remplacez par vos SIREN

Les SIREN absents de votre base sont rendus dans missing. Avec "import_missing": true (et le droit companies:enrich en plus), ils sont importés puis enrichis en file : c'est une dépense.

Lancer un enchaînement, le suivre, l'annuler#

Terminal

curl -s -X POST "$LE_URL/api/v1/lists/prospects-lyon/chains/launch" \
  -H "Authorization: Bearer $LE_CLE" -H "Content-Type: application/json" \
  -d '{"steps":[{"action":"find_website"},{"action":"mail_finder"}]}'

curl -s "$LE_URL/api/v1/lists/prospects-lyon/chains/status" -H "Authorization: Bearer $LE_CLE"

curl -s -X POST "$LE_URL/api/v1/chain-runs/12/cancel" -H "Authorization: Bearer $LE_CLE"

GET /chain-actions donne les actions possibles et le nombre maximal d'étapes. Selon les étapes, un enchaînement consomme vos quotas, des sondes SMTP (Mail Finder), des appels Google Maps ou de l'IA.

Envoyer une liste vers Mail Empire#

Terminal

curl -s -X POST "$LE_URL/api/v1/lists/prospects-lyon/export/mail-empire" \
  -H "Authorization: Bearer $LE_CLE" -H "Content-Type: application/json" \
  -d '{"destinataires":"dirigeants_d_abord"}'

C'est la même file d'envoi que le bouton de l'écran, avec les mêmes filtres. Des données personnelles sortent de Lead Empire : ce droit (lists:export) n'est dans aucun préréglage, sauf « Accès complet ».

Limites et erreurs propres à Lead Empire#

Débit : 60 requêtes par minute par clé par défaut (de 10 à 5 000, choisi à la création). Au-delà : 429 rate_limit_exceeded et Retry-After.
Quotas mensuels de votre formule : 402 quota_exceeded (avec used et limit). Consommation : GET /me.
Au plus 1 000 SIREN par appel (ajout, retrait, envoi, enchaînement).

Code	HTTP	Sens
`missing_bearer_token` · `invalid_token_format` · `invalid_token`	401	Pas de clé, ou clé mal copiée, ou inconnue
`token_revoked` · `token_expired`	401	Clé révoquée ou expirée : créez-en une autre
`tenant_inactive` · `access_stopped`	403	Espace inactif, ou « Tout arrêter » actionné par l'Admin
`ability_missing` · `page_forbidden` · `key_account_missing`	403	Droit manquant, page fermée au compte, compte de la clé disparu
`partial_diffusion`	403	Entreprise en diffusion partielle à l'INSEE
`quota_exceeded`	402	Quota mensuel atteint
`company_not_enriched_yet`	404	L'entreprise n'est pas encore dans la base : enrichissez-la d'abord
`list_busy` · `chain_running` · `mail_empire_not_configured`	409	Une opération tourne déjà, ou Mail Empire n'est pas relié
(validation)	422	`message` et `errors` disent quels paramètres sont refusés
`rate_limit_exceeded`	429	Trop d'appels
`upstream_unavailable`	503	Le registre public interrogé ne répond pas

Le serveur MCP de Lead Empire#

Votre installation a aussi un serveur MCP, https://<votre-installation>/mcp, avec 23 outils qui appellent ces mêmes routes. Voir le MCP direct et la liste des outils.