Referência da API REST

Visão Geral

O LeadHub inclui uma API REST completa que permite a ferramentas externas ler e escrever os seus dados — leads, pipelines, automatizações, formulários e mais. Use-a para integrar com o Zapier, criar dashboards personalizados, ligar o seu website ou automatizar qualquer coisa.

---

URL Base

Todos os pedidos de API vão para:

https://yourdomain.com/api/v1

Substitua yourdomain.com pelo seu domínio LeadHub real.

---

Autenticação

Cada pedido (exceto o health check) requer uma chave de API.

Crie chaves de API no painel de administração em Definições → Chaves de API. Consulte a página de Definições para instruções.

Inclua a sua chave de API em cada pedido como token Bearer no cabeçalho Authorization:

Authorization: Bearer lh_your_api_key_here

Se enviar um pedido sem chave de API, ou com uma chave inválida, receberá uma resposta 401 Unauthorized.

---

Limitação de Taxa

Cada chave de API está limitada a 1.000 pedidos por hora por padrão (configurável por chave). Se exceder este limite, receberá uma resposta 429 Too Many Requests.

Cada resposta inclui estes cabeçalhos para que possa acompanhar o seu uso:

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

X-RateLimit-Reset é um timestamp Unix de quando o seu limite é reiniciado.

---

Paginação

Os endpoints que devolvem listas de registos suportam paginação. Adicione estes parâmetros de query:

Parâmetro	Padrão	Máximo
page	1	—
per_page	15	100

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

---

Formato de Resposta

Resposta de Sucesso

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

Para respostas de registo único (show, create, update), data contém o objeto do registo e meta é omitido.

Resposta de Erro

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

Códigos de erro comuns:

Código	Estado HTTP	Significado
UNAUTHORIZED	401	Chave de API ausente ou inválida
FORBIDDEN	403	A chave de API não tem o scope necessário
NOT_FOUND	404	O registo não existe
VALIDATION_FAILED	422	Os dados do pedido falharam a validação
RATE_LIMITED	429	Demasiados pedidos
SERVER_ERROR	500	Erro inesperado do servidor

---

Health Check

Sem autenticação necessária.

GET /api/v1/health

Resposta:

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

Use isto para verificar se a sua instância LeadHub está acessível antes de fazer outros pedidos.

---

Leads

Scope necessário: read:leads para recuperar, write:leads para criar/atualizar, delete:leads para eliminar.

Listar Leads

GET /api/v1/leads

Parâmetros de query para filtrar:

Parâmetro	Descrição
source	Filtrar por fonte (ex. facebook, website)
status	Filtrar por estado (ex. new, contacted, qualified)
pipeline_id	Filtrar por ID de pipeline
stage_id	Filtrar por ID de etapa do pipeline
assigned_user_id	Filtrar por ID de utilizador atribuído
tag	Filtrar por nome de etiqueta
search	Pesquisar por nome, email ou telefone
created_after	Data ISO 8601 — apenas leads criados após esta data
created_before	Data ISO 8601 — apenas leads criados antes desta data
starred	true para mostrar apenas leads destacados
sort	Campo para ordenar: created_at, updated_at, lead_score, first_name, last_name, email
direction	asc ou desc (padrão: desc)

Obter um Lead

GET /api/v1/leads/{id}

Criar um Lead

POST /api/v1/leads

Corpo do pedido (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 é obrigatório. Todos os outros campos são opcionais.

Atualizar um Lead

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

Envie apenas os campos que pretende atualizar. Mesmos campos que na criação.

Eliminar um Lead

DELETE /api/v1/leads/{id}

Adicionar uma Etiqueta a um Lead

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

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

Remover uma Etiqueta de um Lead

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

---

Pipelines

Scope necessário: 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}

Etapas do 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}

---

Etiquetas

Scope necessário: read:tags ou write:tags

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

---

Utilizadores

Scope necessário: 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}

---

Formulários

Scope necessário: 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}

Submeter um Formulário

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

Corpo: os valores dos campos do formulário como pares chave-valor.

---

Automatizações

Scope necessário: 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}

---

Integrações

Scope necessário: 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 devolve a lista de tipos de integração disponíveis (Facebook, Google Ads, Mailgun, etc.).

---

Ingestão de Leads Recebidos

Um endpoint simplificado para criar leads a partir de fontes externas, webhooks ou ferramentas no-code como Zapier e Make.

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

Autentique com Authorization: Bearer {api_key} e passe o slug do workspace como parâmetro de query.

Corpo do pedido:

{
  "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 é obrigatório. Todos os outros campos são opcionais.

Resposta de sucesso (201):

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

Se o lead já existe (identificado por email ou telefone), is_duplicate é true e o ID do lead existente é devolvido.

---

Exemplos de Código

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();