API-referentie — LeadGrid

01 — Begin hier

Overzicht

De LeadGrid API laat je dossiers aanmaken en beheren, fasen bijwerken, notities koppelen en data synchroniseren met je eigen tools. Elk verzoek retourneert JSON.

Basis-URL

https://leadgrid.io/api/v1

Formaat

JSON (UTF-8)

Auth

Bearer API-sleutel

Beschikbaarheid

Growth-plan

Alle tijdstempels zijn ISO 8601 in UTC. Alle bedragen zijn integers of decimalen in de kleinst praktische eenheid (bijv. euro's, niet centen). Paginering gebruikt page en per_page queryparameters; responses bevatten een meta object met het totale aantal.

02 — Beveiliging

Authenticatie

Elk verzoek moet een API-sleutel bevatten in de Authorization-header. Sleutels beginnen met lg_live_ en zijn gekoppeld aan één organisatie.

1Ga naar Instellingen → API en klik op API-sleutel aanmaken.
2Kies de scopes die je nodig hebt (zie de tabel hieronder) en stel optioneel een vervaldatum in. De volledige sleutel wordt eenmalig getoond — kopieer hem direct.
3Stuur de sleutel als bearer-token mee bij elk verzoek.

curl

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

Beschikbare scopes

Veld	Type	Beschrijving
dossiers:read	scope	Dossiers weergeven en ophalen.
dossiers:write	scope	Dossiers aanmaken, bijwerken en archiveren. Ook vereist om fasen te verplaatsen.
flows:read	scope	Flows weergeven en hun fasen lezen.
notes:read	scope	Notities bij dossiers lezen.
notes:write	scope	Nieuwe notities aan dossiers toevoegen.

Stel je sleutel nooit bloot in client-side code. De sleutel heeft volledige toegang tot je organisatie; behandel hem als een wachtwoord. Als een sleutel uitlekt, verwijder hem dan via Instellingen → API en vervang hem direct.

03 — Resources

Dossiers

Dossiers zijn de entiteiten die je bijhoudt — kandidaten in recruitment of leads in sales. Elk dossier hoort bij precies één flow en bevindt zich in precies één fase.

GET/dossiers

Geef dossiers in je organisatie weer. Ondersteunt filteren en paginering.

Queryparameters

Veld	Type	Beschrijving
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.

Voorbeeldverzoek

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

Voorbeeldrespons

{
  "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

Maak een nieuw dossier aan. Als flow_id wordt weggelaten, wordt de standaardflow voor het opgegeven type gebruikt; het dossier start in de eerste fase van die flow. Stuur application/json voor een gewone aanmaak, of multipart/form-data met een 'cv'-bestandsveld om het dossier aan te maken én een PDF-cv in één atomaire aanroep te koppelen — als de upload mislukt, wordt het dossier teruggedraaid.

Request-body

Veld	Type	Beschrijving
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.

Voorbeeldverzoek

# 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"

Voorbeeldrespons

{
  "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

Haal één dossier op aan de hand van het ID.

Voorbeeldverzoek

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

Voorbeeldrespons

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

PATCH/dossiers/:id

Werk een willekeurige subset van velden bij. Door current_stage_id in te stellen verplaats je het dossier naar een nieuwe fase en wordt een dossier.stage_changed-webhook verstuurd.

Request-body

Veld	Type	Beschrijving
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.

Voorbeeldverzoek

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" }'

Voorbeeldrespons

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

DELETE/dossiers/:id

Archiveert het dossier (soft delete). Zet de status op 'archived' en verstuurt dossier.deleted. Data blijft bewaard en kan worden hersteld via PATCH.

Voorbeeldverzoek

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

Voorbeeldrespons

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

POST/dossiers/:id/cv

Upload een PDF-cv (max. 10 MB) en koppel het aan een bestaand dossier. De upload vervangt een eventueel eerder cv. Accepteert multipart/form-data met een 'cv'-veld, of application/pdf met de PDF-bytes als ruwe body. Verstuurt dossier.updated.

Voorbeeldverzoek

# 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

Voorbeeldrespons

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

04 — Resources

Flows

Flows zijn de pipelines waar dossiers doorheen bewegen. Elke flow heeft geordende fasen met optionele deadlines en winstkansen.

GET/flows

Geef flows in je organisatie weer. Fasen zijn genest en geordend op positie.

Queryparameters

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

Voorbeeldverzoek

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

Voorbeeldrespons

{
  "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

Haal de fasen op voor één flow, gesorteerd op positie. Handig als je het flow_id al weet en alleen de fasen wilt.

Voorbeeldverzoek

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

Voorbeeldrespons

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

05 — Resources

Notities

Notities zijn de tijdlijn van updates die aan een dossier zijn gekoppeld. Ze zijn gesorteerd van oudste naar nieuwste en zijn standaard altijd intern.

GET/dossiers/:id/notes

Geef notities voor een dossier weer, oudste eerst.

Voorbeeldverzoek

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

Voorbeeldrespons

{
  "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

Voeg een nieuwe notitie toe aan een dossier. Verstuurt een note.created-webhook.

Request-body

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

Voorbeeldverzoek

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." }'

Voorbeeldrespons

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

06 — Events

Webhooks

Configureer een webhook-endpoint via Instellingen → API. LeadGrid verstuurt een POST-verzoek met een JSON-body wanneer een van deze events plaatsvindt.

Eventtypen

Veld	Type	Beschrijving
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"
  }
}

Handtekeningverificatie

Elk webhook-verzoek bevat een X-LeadGrid-Signature header met een tijdstempel en een HMAC-SHA256-handtekening van `${"timestamp"}.${"body"}` ondertekend met het geheim van je endpoint. Verifieer deze voordat je de payload vertrouwt.

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 — Referentie

Fouten & limieten

Fouten gebruiken standaard HTTP-statuscodes. De body bevat altijd een error-object met een stabiele code en een leesbare melding.

Error shape

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

Veelvoorkomende foutcodes

Veld	Type	Beschrijving
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.

Growth-ratelimiet

600 req / min / key

429-respons

Retry-After header in seconds

Elke respons bevat X-RateLimit-Limit en X-RateLimit-Remaining headers zodat je terug kunt schakelen voordat je het limiet bereikt.

Bouw verder op je LeadGrid-pipelines.

Overzicht

Authenticatie

Dossiers

Flows

Notities

Webhooks

Handtekeningverificatie

Fouten & limieten