Leads API
Lisez les leads et mettez à jour leur statut depuis vos propres systèmes avec une clé d'API à portée limitée.
Cette page a été traduite de l'anglais. En cas de divergence, la version anglaise fait foi. Lire en anglais
La Leads API permet à votre CRM, à votre entrepôt de données ou à votre automatisation de lire vos leads et de mettre à jour leur statut.
Créez les clés dans Studio sous Integrations → Leads API → New key. Chaque clé possède :
- un nom ;
- des droits :
leads:read(Read leads) et, facultativement,leads:write-status(Change lead status) ; - une expiration de 30, 90, 180 jours ou 1 an.
Les clés ont la forme atl_lead_ suivi de 43 caractères. Elles ne sont affichées qu’une fois, ne sont stockées que sous forme d’empreinte, sont vérifiées à chaque requête et peuvent être révoquées à tout moment (Revoke key). Un environnement de site peut avoir jusqu’à 20 clés actives. La création d’une clé peut exiger une seconde confirmation sur votre téléphone.
URL de base et authentification
Section intitulée « URL de base et authentification »https://<delivery host>/v1/leads-api/environments/{environmentId}Authorization: Bearer atl_lead_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXLes réponses portent Cache-Control: private, no-store. Les erreurs utilisent le format RFC 9457 application/problem+json.
Lister les leads
Section intitulée « Lister les leads »GET /leads?since=2026-10-01T00:00:00Z&limit=50&cursor=…
| Paramètre | Remarques |
|---|---|
since |
Uniquement les leads mis à jour à partir de cet instant. ISO 8601 avec fuseau horaire |
limit |
De 1 à 200, 50 par défaut |
cursor |
Le nextCursor de la réponse précédente |
Les leads arrivent par ordre de modification, du plus ancien au plus récent. La réponse est { "leads": [ … ], "nextCursor": "…" | null }. Continuez à paginer jusqu’à ce que nextCursor soit null, et conservez le dernier updatedAt pour ne récupérer que les modifications la fois suivante.
La liste inclut les leads fusionnés, anonymisés et de test. Vérifiez mergedInto, anonymisedAt et isTest.
Obtenir un lead
Section intitulée « Obtenir un lead »GET /leads/{leadId}
| Champ | Remarques |
|---|---|
id, source |
La source est le formulaire ou le chatbot d’où provient le lead |
form |
{ key, name }, ou null pour les leads de chatbot |
name, email, phone, company, message |
Vides une fois que la conservation a supprimé les données personnelles |
details |
Toutes les autres réponses |
status |
new, contacted, qualified, won, lost ou spam |
isTest |
Envois de test depuis Studio |
version |
Renvoyez-la lorsque vous changez le statut |
mergedInto, anonymisedAt |
Renseignés lorsque le lead a été fusionné ou anonymisé |
createdAt, updatedAt |
Horodatages ISO 8601 |
Changer le statut d’un lead
Section intitulée « Changer le statut d’un lead »PATCH /leads/{leadId}/status avec { "status": "qualified", "expectedVersion": 4 }. Nécessite le droit Change lead status. La modification apparaît dans l’historique du lead comme effectuée par la clé.
Erreurs et limites
Section intitulée « Erreurs et limites »| Statut | Code | Signification |
|---|---|---|
| 401 | CP_UNAUTHENTICATED |
Clé absente, incorrecte, expirée ou révoquée |
| 403 | CP_FORBIDDEN |
La clé n’a pas le droit requis pour cette requête |
| 404 | CP_NOT_FOUND |
Aucun lead de ce type dans cet environnement |
| 409 | CP_VERSION_CONFLICT |
Le lead a changé depuis votre lecture. Relisez-le |
| 422 | REQUEST_SCHEMA_INVALID |
Le corps de la requête ou un paramètre n’est pas valide |
| 422 | CURSOR_INVALID |
Le curseur n’a pas pu être lu |
| 429 | RATE_LIMITED |
Plus de 300 requêtes par minute. Patientez et réessayez |
La limite de débit s’applique par serveur d’API Atlas ; considérez donc 300 requêtes par minute comme un plafond, pas comme une garantie.