Référence API REST

Vue d'ensemble

LeadHub inclut une API REST complète qui permet à des outils externes de lire et d'écrire vos données — leads, pipelines, automatisations, formulaires et plus encore. Utilisez-la pour vous intégrer à Zapier, créer des tableaux de bord personnalisés, connecter votre site web ou automatiser n'importe quoi.

URL de Base

Toutes les requêtes API sont envoyées à :

https://yourdomain.com/api/v1

Remplacez yourdomain.com par votre domaine LeadHub réel.

Authentification

Chaque requête (sauf le health check) nécessite une clé API.

Créez des clés API dans le panneau d'administration sous Paramètres → Clés API. Consultez la page Paramètres pour les instructions.

Incluez votre clé API dans chaque requête comme token Bearer dans l'en-tête Authorization :

Authorization: Bearer lh_your_api_key_here

Si vous envoyez une requête sans clé API ou avec une clé invalide, vous recevrez une réponse 401 Unauthorized.

Limitation de Débit

Chaque clé API est limitée à 1 000 requêtes par heure par défaut (configurable par clé). Si vous dépassez cette limite, vous recevrez une réponse 429 Too Many Requests.

Chaque réponse inclut ces en-têtes pour vous permettre de suivre votre utilisation :

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1711580400

X-RateLimit-Reset est un timestamp Unix indiquant quand votre limite se réinitialise.

Pagination

Les endpoints qui retournent des listes d'enregistrements supportent la pagination. Ajoutez ces paramètres de requête :

Paramètre	Défaut	Maximum
`page`	`1`	—
`per_page`	`15`	`100`

Exemple : GET /api/v1/leads?page=2&per_page=25

Format de Réponse

Réponse Réussie

{
  "data": { ... },
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 73,
    "from": 1,
    "to": 15
  },
  "links": {
    "first": "https://yourdomain.com/api/v1/leads?page=1",
    "last": "https://yourdomain.com/api/v1/leads?page=5",
    "prev": null,
    "next": "https://yourdomain.com/api/v1/leads?page=2",
    "self": "https://yourdomain.com/api/v1/leads?page=1"
  }
}

Pour les réponses à un seul enregistrement (show, create, update), data contient l'objet enregistrement et meta est omis.

Réponse d'Erreur

{
  "status": "error",
  "message": "The given data was invalid.",
  "code": "VALIDATION_FAILED",
  "errors": {
    "email": ["The email field must be a valid email address."]
  }
}

Codes d'erreur courants :

Code	Statut HTTP	Signification
`UNAUTHORIZED`	401	Clé API manquante ou invalide
`FORBIDDEN`	403	La clé API manque du scope requis
`NOT_FOUND`	404	L'enregistrement n'existe pas
`VALIDATION_FAILED`	422	Les données de la requête ont échoué la validation
`RATE_LIMITED`	429	Trop de requêtes
`SERVER_ERROR`	500	Erreur serveur inattendue

Health Check

Aucune authentification requise.

GET /api/v1/health

Réponse :

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-03-28T09:15:00+00:00"
}

Utilisez ceci pour vérifier si votre instance LeadHub est accessible avant de faire d'autres requêtes.

Leads

Scope requis : read:leads pour récupérer, write:leads pour créer/mettre à jour, delete:leads pour supprimer.

Lister les Leads

GET /api/v1/leads

Paramètres de requête pour le filtrage :

Paramètre	Description
`source`	Filtrer par source (ex. `facebook`, `website`)
`status`	Filtrer par statut (ex. `new`, `contacted`, `qualified`)
`pipeline_id`	Filtrer par ID de pipeline
`stage_id`	Filtrer par ID d'étape de pipeline
`assigned_user_id`	Filtrer par ID d'utilisateur assigné
`tag`	Filtrer par nom de tag
`search`	Rechercher par nom, email ou téléphone
`created_after`	Date ISO 8601 — uniquement les leads créés après cette date
`created_before`	Date ISO 8601 — uniquement les leads créés avant cette date
`starred`	`true` pour afficher uniquement les leads mis en favoris
`sort`	Champ de tri : `created_at`, `updated_at`, `lead_score`, `first_name`, `last_name`, `email`
`direction`	`asc` ou `desc` (défaut : `desc`)

Obtenir un Lead

GET /api/v1/leads/{id}

Créer un Lead

POST /api/v1/leads

Corps de la requête (JSON) :

{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "[email protected]",
  "phone": "+14155551234",
  "source": "website",
  "status": "new",
  "pipeline_id": 1,
  "pipeline_stage_id": 2,
  "assigned_user_id": 5,
  "notes": "Interested in the enterprise plan.",
  "custom_fields": {
    "budget": "10000"
  },
  "tags": ["hot-lead", "enterprise"]
}

first_name est obligatoire. Tous les autres champs sont optionnels.

Mettre à Jour un Lead

PUT /api/v1/leads/{id}
PATCH /api/v1/leads/{id}

Envoyez uniquement les champs que vous souhaitez mettre à jour. Mêmes champs que pour la création.

Supprimer un Lead

DELETE /api/v1/leads/{id}

Ajouter un Tag à un Lead

POST /api/v1/leads/{id}/tags

Corps : { "tag": "vip-client" }

Retirer un Tag d'un Lead

DELETE /api/v1/leads/{id}/tags/{tag}

Pipelines

Scope requis : read:pipelines ou write:pipelines

GET    /api/v1/pipelines
POST   /api/v1/pipelines
GET    /api/v1/pipelines/{id}
PUT    /api/v1/pipelines/{id}
PATCH  /api/v1/pipelines/{id}
DELETE /api/v1/pipelines/{id}

Étapes du Pipeline

GET    /api/v1/pipelines/{pipeline_id}/stages
POST   /api/v1/pipelines/{pipeline_id}/stages
GET    /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
PUT    /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
PATCH  /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
DELETE /api/v1/pipelines/{pipeline_id}/stages/{stage_id}

Utilisateurs

Scope requis : read:users, write:users ou delete:users

GET    /api/v1/users
POST   /api/v1/users
GET    /api/v1/users/{id}
PUT    /api/v1/users/{id}
PATCH  /api/v1/users/{id}
DELETE /api/v1/users/{id}

Formulaires

Scope requis : read:forms, write:forms ou delete:forms

GET    /api/v1/forms
POST   /api/v1/forms
GET    /api/v1/forms/{id}
PUT    /api/v1/forms/{id}
PATCH  /api/v1/forms/{id}
DELETE /api/v1/forms/{id}

Soumettre un Formulaire

POST /api/v1/forms/{id}/submissions

Corps : les valeurs des champs du formulaire sous forme de paires clé-valeur.

Automatisations

Scope requis : read:automations, write:automations ou delete:automations

GET    /api/v1/automations
POST   /api/v1/automations
GET    /api/v1/automations/{id}
PUT    /api/v1/automations/{id}
PATCH  /api/v1/automations/{id}
DELETE /api/v1/automations/{id}

Intégrations

Scope requis : read:integrations ou write:integrations

GET    /api/v1/integrations/types
GET    /api/v1/integrations
POST   /api/v1/integrations
GET    /api/v1/integrations/{id}
PUT    /api/v1/integrations/{id}
PATCH  /api/v1/integrations/{id}
DELETE /api/v1/integrations/{id}

GET /api/v1/integrations/types retourne la liste des types d'intégration disponibles (Facebook, Google Ads, Mailgun, etc.).

Ingestion de Leads Entrants

Un endpoint simplifié pour créer des leads depuis des sources externes, des webhooks ou des outils no-code comme Zapier et Make.

POST /api/inbound/leads?tenant={workspace-slug}

Authentifiez-vous avec Authorization: Bearer {api_key} et passez le slug du workspace en paramètre de requête.

Corps de la requête :

{
  "email": "[email protected]",
  "first_name": "Sarah",
  "last_name": "Johnson",
  "phone": "+14155551234",
  "company": "Tech Corp",
  "source": "zapier",
  "notes": "Came from newsletter signup",
  "tags": ["newsletter"],
  "custom_fields": {
    "utm_campaign": "spring-promo"
  }
}

email est obligatoire. Tous les autres champs sont optionnels.

Réponse succès (201) :

{
  "status": "created",
  "lead_id": 1842,
  "is_duplicate": false
}

Si le lead existe déjà (correspondance par email ou téléphone), is_duplicate est true et l'ID du lead existant est retourné.

Exemples de Code

cURL

curl -X GET "https://yourdomain.com/api/v1/leads?status=new&per_page=25" \
  -H "Authorization: Bearer lh_your_api_key_here" \
  -H "Accept: application/json"

curl -X POST "https://yourdomain.com/api/v1/leads" \
  -H "Authorization: Bearer lh_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Sarah","email":"[email protected]","source":"api"}'

PHP

$apiKey = 'lh_your_api_key_here';
$baseUrl = 'https://yourdomain.com/api/v1';

// List leads
$response = file_get_contents($baseUrl . '/leads', false, stream_context_create([
    'http' => [
        'header' => "Authorization: Bearer {$apiKey}\r\nAccept: application/json\r\n",
    ],
]));
$leads = json_decode($response, true);

// Create a lead
$ch = curl_init($baseUrl . '/leads');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer {$apiKey}",
    "Content-Type: application/json",
    "Accept: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'first_name' => 'Sarah',
    'email'      => '[email protected]',
    'source'     => 'api',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript (fetch)

const apiKey = 'lh_your_api_key_here';
const baseUrl = 'https://yourdomain.com/api/v1';

// List leads
const response = await fetch(`${baseUrl}/leads?status=new`, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Accept': 'application/json',
  },
});
const { data, meta } = await response.json();

// Create a lead
const createResponse = await fetch(`${baseUrl}/leads`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'Sarah',
    email: '[email protected]',
    source: 'website',
  }),
});
const newLead = await createResponse.json();

Vue d'ensemble​

URL de Base​

Authentification​

Limitation de Débit​

Pagination​

Format de Réponse​

Réponse Réussie​

Réponse d'Erreur​

Health Check​

Leads​

Lister les Leads​

Obtenir un Lead​

Créer un Lead​

Mettre à Jour un Lead​

Supprimer un Lead​

Ajouter un Tag à un Lead​

Retirer un Tag d'un Lead​

Pipelines​

Étapes du Pipeline​

Tags​

Utilisateurs​

Formulaires​

Soumettre un Formulaire​

Automatisations​

Intégrations​

Ingestion de Leads Entrants​

Exemples de Code​

cURL​

PHP​

JavaScript (fetch)​