Référence API — LeadGrid

01 — Par ici

Aperçu

L'API LeadGrid te permet de créer et gérer des dossiers, de mettre à jour les étapes, d'attacher des notes et de synchroniser des données avec tes propres outils. Chaque requête retourne du JSON.

URL de base

https://leadgrid.io/api/v1

Format

JSON (UTF-8)

Auth

Bearer clé API

Disponibilité

Plan Growth

Tous les horodatages sont en ISO 8601 UTC. Tous les montants sont des entiers ou des décimaux dans la plus petite unité pratique (p. ex. euros, pas centimes). La pagination utilise page et per_page comme paramètres de requête ; les réponses incluent un objet meta avec le nombre total.

02 — Sécurité

Authentification

Chaque requête doit comporter une clé API dans l'en-tête Authorization. Les clés commencent par lg_live_ et sont liées à une seule organisation.

1Rends-toi dans Paramètres → API et clique sur Créer une clé API.
2Choisis les scopes dont tu as besoin (voir le tableau ci-dessous) et définis éventuellement une date d'expiration. La clé complète est affichée une seule fois — copie-la immédiatement.
3Envoie la clé comme token Bearer à chaque requête.

curl

curl https://leadgrid.io/api/v1/dossiers \
  -H "Authorization: Bearer lg_live_your_key_here"

Scopes disponibles

Champ	Type	Description
dossiers:read	scope	Lister et récupérer des dossiers.
dossiers:write	scope	Créer, mettre à jour et archiver des dossiers. Également requis pour déplacer des étapes.
flows:read	scope	Lister les flows et lire leurs étapes.
notes:read	scope	Lire les notes sur les dossiers.
notes:write	scope	Ajouter de nouvelles notes aux dossiers.

N'expose jamais ta clé dans du code côté client. La clé donne un accès complet à ton organisation ; traite-la comme un mot de passe. Si une clé fuite, supprime-la depuis Paramètres → API et remplace-la immédiatement.

03 — Ressources

Dossiers

Les dossiers sont les entités que tu suis — candidats en recrutement ou prospects en vente. Chaque dossier appartient à exactement un flow et se trouve dans exactement une étape.

GET/dossiers

Lister les dossiers de ton organisation. Supporte le filtrage et la pagination.

Paramètres de requête

Champ	Type	Description
type	string	'candidate' or 'sales'.
status	string	'active', 'won', 'lost' or 'archived'.
stage_id	uuid	Return only dossiers currently in this stage.
page	integer	1-based page number. Default: 1.
per_page	integer	Items per page (max 100). Default: 25.

Exemple de requête

curl "https://leadgrid.io/api/v1/dossiers?type=sales&status=active" \
  -H "Authorization: Bearer lg_live_your_key"

Exemple de réponse

{
  "data": [
    {
      "id": "6f2b…",
      "type": "sales",
      "name": "Rabobank — Talent rollout",
      "company": "Rabobank",
      "contact_person": "Mark de Vries",
      "deal_size": 45000,
      "deal_currency": "EUR",
      "status": "active",
      "current_stage_id": "c3e1…",
      "assigned_to": "ab12…",
      "created_at": "2026-04-10T09:21:14Z"
    }
  ],
  "meta": { "total": 34, "page": 1, "per_page": 25 }
}

POST/dossiers

Créer un nouveau dossier. Si flow_id est omis, le flow par défaut pour le type donné est utilisé ; le dossier démarre à la première étape de ce flow. Envoie application/json pour une création simple, ou multipart/form-data avec un champ 'cv' pour créer le dossier ET joindre un CV PDF en un seul appel atomique — si l'upload échoue, le dossier est annulé.

Corps de la requête

Champ	Type	Description
type*	string	'candidate' or 'sales'.
name*	string	For candidates: the person's name. For sales: deal or account name.
email	string	Primary contact email.
phone	string	Primary contact phone.
company	string	Candidate: current employer. Sales: target company.
role	string	Candidate: role they're applying for. Sales: role of the contact.
flow_id	uuid	Override the default flow. Must belong to your organization.
assigned_to	uuid	User ID of the member to assign this dossier to.
intake_notes	string	Director/intake notes shown in the dossier drawer.
contact_person	string	Sales only. Named contact at the target company.
deal_size	number	Sales only. Expected contract value.
deal_currency	string	Sales only. ISO 4217 currency code (e.g. 'EUR').
cv	file (pdf)	multipart/form-data only. Optional PDF CV (max 10 MB). Uploaded and attached in the same call. If the upload fails, the dossier is rolled back.

Exemple de requête

# JSON — plain create
curl -X POST https://leadgrid.io/api/v1/dossiers \
  -H "Authorization: Bearer lg_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sales",
    "name": "KLM — Cabin crew hiring",
    "company": "KLM",
    "contact_person": "Pieter van Leeuwen",
    "deal_size": 62000,
    "deal_currency": "EUR"
  }'

# multipart — create + attach CV in one call
curl -X POST https://leadgrid.io/api/v1/dossiers \
  -H "Authorization: Bearer lg_live_your_key" \
  -F "type=candidate" \
  -F "name=Sophie van Dijk" \
  -F "role=Senior Frontend Engineer" \
  -F "email=sophie@example.com" \
  -F "cv=@./resume.pdf"

Exemple de réponse

{
  "data": {
    "id": "a91c…",
    "type": "candidate",
    "name": "Sophie van Dijk",
    "cv_url": "<org-id>/dossiers/a91c…/cv.pdf",
    "status": "active",
    "current_stage_id": "b77f…",
    "created_at": "2026-04-15T12:03:40Z"
  }
}

GET/dossiers/:id

Récupérer un seul dossier par son ID.

Exemple de requête

curl https://leadgrid.io/api/v1/dossiers/a91c… \
  -H "Authorization: Bearer lg_live_your_key"

Exemple de réponse

{
  "data": {
    "id": "a91c…",
    "type": "sales",
    "name": "KLM — Cabin crew hiring",
    "deal_size": 62000,
    "current_stage_id": "b77f…"
  }
}

PATCH/dossiers/:id

Mettre à jour un sous-ensemble quelconque de champs. Définir current_stage_id déplace le dossier vers une nouvelle étape et émet un webhook dossier.stage_changed.

Corps de la requête

Champ	Type	Description
name	string	Rename the dossier.
email	string	Update primary contact email.
phone	string	Update phone.
company	string	Update company / employer.
role	string	Update role.
contact_person	string	Sales only.
deal_size	number	Sales only.
deal_currency	string	Sales only.
status	string	'active', 'won', 'lost' or 'archived'.
assigned_to	uuid	Reassign to another member. Null to unassign.
intake_notes	string	Replace intake notes.
current_stage_id	uuid	Move to a new stage. Must belong to the dossier's flow.

Exemple de requête

curl -X PATCH https://leadgrid.io/api/v1/dossiers/a91c… \
  -H "Authorization: Bearer lg_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "current_stage_id": "d8e2…", "status": "active" }'

Exemple de réponse

{
  "data": {
    "id": "a91c…",
    "current_stage_id": "d8e2…",
    "status": "active"
  }
}

DELETE/dossiers/:id

Archive le dossier (suppression douce). Définit le statut sur 'archived' et émet dossier.deleted. Les données sont conservées et peuvent être restaurées via PATCH.

Exemple de requête

curl -X DELETE https://leadgrid.io/api/v1/dossiers/a91c… \
  -H "Authorization: Bearer lg_live_your_key"

Exemple de réponse

{
  "data": {
    "id": "a91c…",
    "status": "archived"
  }
}

POST/dossiers/:id/cv

Uploader un CV PDF (max. 10 Mo) et l'attacher à un dossier existant. L'upload remplace tout CV précédent. Accepte multipart/form-data avec un champ 'cv', ou application/pdf avec les octets PDF comme corps brut. Émet dossier.updated.

Exemple de requête

# multipart/form-data
curl -X POST https://leadgrid.io/api/v1/dossiers/a91c…/cv \
  -H "Authorization: Bearer lg_live_your_key" \
  -F "cv=@./resume.pdf"

# raw application/pdf
curl -X POST https://leadgrid.io/api/v1/dossiers/a91c…/cv \
  -H "Authorization: Bearer lg_live_your_key" \
  -H "Content-Type: application/pdf" \
  --data-binary @./resume.pdf

Exemple de réponse

{
  "data": {
    "id": "a91c…",
    "cv_url": "<org-id>/dossiers/a91c…/cv.pdf"
  }
}

04 — Ressources

Flows

Les flows sont les pipelines par lesquels les dossiers progressent. Chaque flow comporte des étapes ordonnées avec des délais et des probabilités de gain optionnels.

GET/flows

Lister les flows de ton organisation. Les étapes sont imbriquées et ordonnées par position.

Paramètres de requête

Champ	Type	Description
type	string	Filter to 'candidate' or 'sales'.
page	integer	Page number. Default: 1.
per_page	integer	Items per page. Default: 25.

Exemple de requête

curl "https://leadgrid.io/api/v1/flows?type=sales" \
  -H "Authorization: Bearer lg_live_your_key"

Exemple de réponse

{
  "data": [
    {
      "id": "f01a…",
      "name": "Sales Flow",
      "type": "sales",
      "is_default": true,
      "stages": [
        {
          "id": "s1…",
          "name": "Lead",
          "position": 1,
          "deadline_days": 3,
          "win_probability": 14,
          "color": "#FF5C35"
        },
        {
          "id": "s2…",
          "name": "Discovery",
          "position": 2,
          "deadline_days": 5,
          "win_probability": 29,
          "color": "#22C55E"
        }
      ]
    }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 25 }
}

GET/flows/:id/stages

Récupérer les étapes d'un seul flow, triées par position. Utile si tu connais déjà le flow_id et veux uniquement les étapes.

Exemple de requête

curl https://leadgrid.io/api/v1/flows/f01a…/stages \
  -H "Authorization: Bearer lg_live_your_key"

Exemple de réponse

{
  "data": [
    {
      "id": "s1…",
      "name": "Lead",
      "position": 1,
      "deadline_days": 3,
      "win_probability": 14
    }
  ],
  "meta": { "total": 6, "page": 1, "per_page": 6 }
}

05 — Ressources

Notes

Les notes constituent la chronologie des mises à jour attachées à un dossier. Elles sont triées de la plus ancienne à la plus récente et sont toujours internes par défaut.

GET/dossiers/:id/notes

Lister les notes d'un dossier, les plus anciennes en premier.

Exemple de requête

curl https://leadgrid.io/api/v1/dossiers/a91c…/notes \
  -H "Authorization: Bearer lg_live_your_key"

Exemple de réponse

{
  "data": [
    {
      "id": "n1…",
      "dossier_id": "a91c…",
      "content": "Had a great first call — strong culture fit.",
      "is_internal": true,
      "created_at": "2026-04-14T09:12:30Z"
    }
  ],
  "meta": { "total": 3, "page": 1, "per_page": 25 }
}

POST/dossiers/:id/notes

Ajouter une nouvelle note à un dossier. Émet un webhook note.created.

Corps de la requête

Champ	Type	Description
content*	string	The note text. Cannot be empty.
is_internal	boolean	Default: true. Internal notes are not shared.

Exemple de requête

curl -X POST https://leadgrid.io/api/v1/dossiers/a91c…/notes \
  -H "Authorization: Bearer lg_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Followed up by email." }'

Exemple de réponse

{
  "data": {
    "id": "n2…",
    "dossier_id": "a91c…",
    "content": "Followed up by email.",
    "is_internal": true,
    "created_at": "2026-04-15T12:04:10Z"
  }
}

06 — Événements

Webhooks

Configure un endpoint webhook dans Paramètres → API. LeadGrid envoie une requête POST avec un corps JSON lorsque l'un de ces événements se produit.

Types d'événements

Champ	Type	Description
dossier.created	event	A new dossier was created (via API, UI or email).
dossier.updated	event	Any field on a dossier changed. Fires alongside stage_changed when applicable.
dossier.stage_changed	event	current_stage_id was updated.
dossier.deleted	event	Dossier was archived (status set to 'archived').
note.created	event	A new note was added to a dossier.

Example payload

POST https://your-app.com/webhooks/leadgrid
Content-Type: application/json
X-LeadGrid-Signature: t=1713178230,v1=3b2c4f…

{
  "id": "evt_…",
  "type": "dossier.stage_changed",
  "created_at": "2026-04-15T12:04:10Z",
  "data": {
    "id": "a91c…",
    "current_stage_id": "d8e2…",
    "status": "active"
  }
}

Vérification de signature

Chaque requête webhook inclut un en-tête X-LeadGrid-Signature contenant un horodatage et une signature HMAC-SHA256 de `${"timestamp"}.${"body"}` signée avec le secret de ton endpoint. Vérifie-la avant de faire confiance au payload.

node.js (verification)

import crypto from "node:crypto";

export function verifyLeadGridSignature(
  header: string,
  body: string,
  secret: string,
) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=")),
  );
  const { t, v1 } = parts as { t: string; v1: string };

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${body}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(v1),
  );
}

07 — Référence

Erreurs & limites de débit

Les erreurs utilisent les codes de statut HTTP standard. Le corps contient toujours un objet error avec un code stable et un message lisible.

Error shape

{
  "error": {
    "code": "not_found",
    "message": "Dossier not found."
  }
}

Codes d'erreur courants

Champ	Type	Description
unauthorized	401	Missing, malformed or invalid API key. Also returned for expired keys.
plan_required	402	Your organization is on Free or Pro. API access requires Growth.
forbidden	403	The API key doesn't include the required scope for this action.
not_found	404	The resource doesn't exist, or doesn't belong to your organization.
invalid_body	400	Missing required field, unknown value or malformed JSON.
rate_limited	429	You've exceeded the rate limit for your plan. Retry after the time in the Retry-After header.
internal	500	Unexpected server error. Safe to retry.

Limite de débit Growth

600 req / min / key

Réponse 429

Retry-After header in seconds

Chaque réponse inclut X-RateLimit-Limit et X-RateLimit-Remaining en-têtes pour que tu puisses ralentir avant d'atteindre la limite.

Développe sur tes pipelines LeadGrid.

Aperçu

Authentification

Dossiers

Flows

Notes

Webhooks

Vérification de signature

Erreurs & limites de débit