Référence de l'API
L'essentiel pour appeler l'API de Caryon Lead depuis un script ou un outil : authentification, ressources, pagination, erreurs et limites.
L'API de Caryon Lead permet de lire et d'écrire vos entreprises, contacts, opportunités et actions depuis vos propres outils. Elle est incluse dans les formules Business et Enterprise, et pendant l'essai.
- Adresse de base :
https://api.caryon.app/lead/v1 - Description complète (format OpenAPI, pour vos outils) : https://api.caryon.app/lead/v1/openapi.json
Authentification
Créez une clé API et envoyez-la dans chaque appel :
Authorization: Bearer cyk_…La clé agit pour un espace, avec les droits du rôle choisi ; une clé en lecture seule ne peut pas écrire.
Ressources
| Ressource | Accès |
|---|---|
companies (entreprises) | lecture, écriture |
contacts | lecture, écriture |
deals (opportunités) | lecture, écriture |
actions | lecture, écriture |
exchanges (échanges passés) | lecture, écriture |
pipelines | lecture seule |
users (membres) | lecture seule |
Pour chaque ressource :
GET /ressource: la liste ;GET /ressource/:id: le détail ;POST /ressource: créer ;PATCH /ressource/:id: modifier ;POST /ressource/:id/archiveetPOST /ressource/:id/restore: archiver et restaurer. L'archivage accepte un motif facultatif,{ "reason": "Doublon" }(500 caractères au plus), affiché dans le Journal.
Pas de suppression
L'API ne supprime jamais rien : DELETE répond 405. Archivez, et restaurez au besoin. Les listes masquent les éléments archivés ; ajoutez ?include_archived=true pour les voir.
Si le membre de la clé a relié son agenda Google ou CalDAV, ses rendez-vous créés, déplacés, annulés ou archivés par l'API y sont reportés comme depuis Caryon Lead, invitations comprises s'il les a activées.
Pagination
Les listes sont paginées par curseur. Une réponse a la forme { "data": [...], "next_cursor": "..." } : pour la page suivante, renvoyez ?cursor=<next_cursor>. next_cursor vaut null sur la dernière page. limit règle la taille d'une page, de 1 à 100 (50 par défaut).
curl "https://api.caryon.app/lead/v1/contacts?limit=100&cursor=eyJ0Ijo…" \
-H "Authorization: Bearer cyk_…"Erreurs
Une erreur a toujours cette forme :
{ "error": { "code": "forbidden", "message": "…" } }| Code | HTTP | Signification |
|---|---|---|
unauthorized | 401 | Clé absente, invalide, expirée ou révoquée |
plan_required | 403 | La formule de l'espace n'inclut pas l'API |
feature_disabled | 403 | Un administrateur a désactivé les clés API |
seat_required | 403 | Le membre n'a pas de siège Caryon Lead |
forbidden | 403 | Le rôle de la clé ne permet pas ce geste |
rate_limited | 429 | Trop d'appels |
Limites
30 appels par minute et 5 000 par jour par clé. Au-delà, l'API répond 429 avec un en-tête Retry-After : le nombre de secondes à attendre.
Exemple
curl https://api.caryon.app/lead/v1/companies \
-H "Authorization: Bearer cyk_…"Chaque écriture est tracée dans le Journal des modifications, « via la clé API » utilisée. Pour piloter Caryon Lead en langage naturel plutôt qu'en code, voir Brancher un agent IA.
Une question sans réponse ici ? Écrivez-nous à contact@caryon.app.