Referencia API — LeadGrid

01 — Empieza aquí

Resumen

La API de LeadGrid te permite crear y gestionar dossiers, actualizar etapas, adjuntar notas y sincronizar datos con tus propias herramientas. Cada solicitud devuelve JSON.

URL base

https://leadgrid.io/api/v1

Formato

JSON (UTF-8)

Auth

Bearer clave API

Disponibilidad

Plan Growth

Todas las marcas de tiempo están en ISO 8601 UTC. Todos los importes son enteros o decimales en la unidad más práctica (p. ej. euros, no céntimos). La paginación usa page y per_page como parámetros de consulta; las respuestas incluyen un objeto meta con el recuento total.

02 — Seguridad

Autenticación

Cada solicitud debe incluir una clave API en la cabecera Authorization. Las claves comienzan con lg_live_ y están vinculadas a una sola organización.

1Ve a Ajustes → API y haz clic en Crear clave API.
2Elige los scopes que necesitas (ver tabla a continuación) y, opcionalmente, establece una fecha de caducidad. La clave completa se muestra una sola vez — cópiala de inmediato.
3Envía la clave como token Bearer en cada solicitud.

curl

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

Scopes disponibles

Campo	Tipo	Descripción
dossiers:read	scope	Listar y recuperar dossiers.
dossiers:write	scope	Crear, actualizar y archivar dossiers. También necesario para mover etapas.
flows:read	scope	Listar flows y leer sus etapas.
notes:read	scope	Leer notas en dossiers.
notes:write	scope	Añadir nuevas notas a dossiers.

Nunca expongas tu clave en código del lado del cliente. La clave tiene acceso completo a tu organización; trátala como una contraseña. Si una clave se filtra, elimínala desde Ajustes → API y rota de inmediato.

03 — Recursos

Dossiers

Los dossiers son las entidades que rastreas — candidatos en selección o leads en ventas. Cada dossier pertenece exactamente a un flow y se encuentra en exactamente una etapa.

GET/dossiers

Listar los dossiers de tu organización. Admite filtrado y paginación.

Parámetros de consulta

Campo	Tipo	Descripción
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.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Crear un nuevo dossier. Si se omite flow_id, se usa el flow predeterminado para el tipo dado; el dossier comienza en la primera etapa de ese flow. Envía application/json para una creación simple, o multipart/form-data con un campo de archivo 'cv' para crear el dossier Y adjuntar un CV en PDF en una sola llamada atómica — si la subida falla, el dossier se revierte.

Cuerpo de la solicitud

Campo	Tipo	Descripción
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.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Recuperar un solo dossier por ID.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

PATCH/dossiers/:id

Actualizar cualquier subconjunto de campos. Establecer current_stage_id mueve el dossier a una nueva etapa y emite un webhook dossier.stage_changed.

Cuerpo de la solicitud

Campo	Tipo	Descripción
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.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

DELETE/dossiers/:id

Archiva el dossier (eliminación suave). Establece el estado en 'archived' y emite dossier.deleted. Los datos se conservan y se pueden restaurar mediante PATCH.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

POST/dossiers/:id/cv

Subir un CV en PDF (máx. 10 MB) y adjuntarlo a un dossier existente. La subida reemplaza cualquier CV previo. Acepta multipart/form-data con un campo 'cv', o application/pdf con los bytes del PDF como cuerpo sin formato. Emite dossier.updated.

Ejemplo de solicitud

# 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

Ejemplo de respuesta

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

04 — Recursos

Flows

Los flows son los pipelines por los que se mueven los dossiers. Cada flow tiene etapas ordenadas con plazos opcionales y probabilidades de cierre.

GET/flows

Listar los flows de tu organización. Las etapas están anidadas y ordenadas por posición.

Parámetros de consulta

Campo	Tipo	Descripción
type	string	Filter to 'candidate' or 'sales'.
page	integer	Page number. Default: 1.
per_page	integer	Items per page. Default: 25.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Obtener las etapas de un solo flow, ordenadas por posición. Útil si ya conoces el flow_id y solo quieres las etapas.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

05 — Recursos

Notas

Las notas son la línea de tiempo de actualizaciones adjuntas a un dossier. Están ordenadas de más antigua a más reciente y siempre son internas por defecto.

GET/dossiers/:id/notes

Listar las notas de un dossier, las más antiguas primero.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Añadir una nueva nota a un dossier. Emite un webhook note.created.

Cuerpo de la solicitud

Campo	Tipo	Descripción
content*	string	The note text. Cannot be empty.
is_internal	boolean	Default: true. Internal notes are not shared.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

06 — Eventos

Webhooks

Configura un endpoint de webhook en Ajustes → API. LeadGrid envía una solicitud POST con un cuerpo JSON cuando ocurre cualquiera de estos eventos.

Tipos de eventos

Campo	Tipo	Descripción
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"
  }
}

Verificación de firma

Cada solicitud de webhook incluye una cabecera X-LeadGrid-Signature que contiene una marca de tiempo y una firma HMAC-SHA256 de `${"timestamp"}.${"body"}` firmada con el secreto de tu endpoint. Verifícala antes de confiar en el 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 — Referencia

Errores y límites de solicitudes

Los errores usan códigos de estado HTTP estándar. El cuerpo siempre contiene un objeto de error con un código estable y un mensaje legible.

Error shape

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

Códigos de error comunes

Campo	Tipo	Descripción
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.

Límite de solicitudes Growth

600 req / min / key

Respuesta 429

Retry-After header in seconds

Cada respuesta incluye X-RateLimit-Limit y X-RateLimit-Remaining cabeceras para que puedas reducir la velocidad antes de alcanzar el límite.

Construye sobre tus pipelines de LeadGrid.

Resumen

Autenticación

Dossiers

Flows

Notas

Webhooks

Verificación de firma

Errores y límites de solicitudes