Leads API

Endpoints para listar, criar, atualizar e gerenciar leads. Para sincronização em lote, recomendamos usar a Sync API.

GET/api/v1/integration/leadsleads:read

Listar leads com paginação e filtros

Query Parameters

Campo	Tipo	Descricao
`page`	number	Página atual (default: 1) Ex: `1`
`limit`	number	Itens por página (default: 20, max: 100) Ex: `20`
`status`	string	Filtrar por status Ex: `open`
`priority`	string	Filtrar por prioridade Ex: `high`
`source`	string	Filtrar por origem Ex: `whatsapp`
`tag`	string	Filtrar por tag (nome ou ID)
`search`	string	Busca por nome, email ou telefone
`createdAfter`	date	Criados após esta data (ISO 8601)
`createdBefore`	date	Criados antes desta data (ISO 8601)

Exemplo

Bash

curl "https://dev-api-tools.helbioads.com/api/v1/integration/leads?status=open&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Resposta

JSON

{
  "success": true,
  "data": {
    "leads": [
      {
        "id": "clx123...",
        "externalId": "lead_001",
        "status": "open",
        "priority": "high",
        "contact": {
          "id": "clx456...",
          "name": "João Silva",
          "email": "joao@email.com"
        },
        "tags": ["interessado", "premium"],
        "createdAt": "2024-01-15T10:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 150,
      "totalPages": 15
    }
  }
}

GET/api/v1/integration/leads/:identifierleads:read

Buscar lead por ID ou externalId

Path Parameters

Campo	Tipo	Descricao
`id`obrigatório	string	ID do lead (UUID) ou externalId

Bash

# Por ID interno
curl "https://dev-api-tools.helbioads.com/api/v1/integration/leads/clx123abc456" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Por externalId
curl "https://dev-api-tools.helbioads.com/api/v1/integration/leads/meu-lead-001" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/v1/integration/leadsleads:write

Criar novo lead

Body Parameters

Campo	Tipo	Descricao
`createContactIfNotFound`	boolean	Quando false, nao cria contato novo se nao encontrar referencia por protocol/externalId/email/phone. Retorna 404. Ex: `false`
`protocol`	string	Protocolo do Magic Link para vincular a lead existente. Quando fornecido e encontrado, vincula os dados ao lead do Magic Link. Ex: `ML-20251030-143052-A8F3D-META`
`externalId`	string	Seu ID único para o lead. Obrigatório se protocol não for fornecido ou não encontrado.
`contactId`	string	ID de um contato existente
`contact`	object	Dados para criar novo contato
`status`	enum	Status inicial (default: open)
`priority`	enum	Prioridade (default: medium)
`source`	enum	Origem do lead
`estimatedValue`	number	Valor estimado da oportunidade (BRL) Ex: `5000`
`saleDate`	string (ISO 8601)	Data/hora em que a venda ocorreu. Usada como timestamp nas conversões offline para Google Ads e Meta Ads. Ex: `2026-05-14T11:00:00.000Z`
`notes`	string	Notas sobre o lead
`tags`	string[]	Tags a associar

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/leads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "lead-001",
    "contact": {
      "name": "Maria Santos",
      "email": "maria@empresa.com",
      "phone": "+5511988888888"
    },
    "status": "open",
    "priority": "high",
    "source": "api",
    "tags": ["api-test"]
  }'

Criar lead sem criar contato novo

Quando createContactIfNotFound for false, o lead so sera criado ou atualizado se a API conseguir localizar um contato ja existente pelas referencias enviadas.

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/leads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "lead-001",
    "createContactIfNotFound": false,
    "contact": {
      "email": "maria@empresa.com"
    },
    "status": "in_progress"
  }'

🔗 Vinculação por Protocolo (Magic Link)

Ao enviar o campo protocol, o sistema busca um lead existente criado via Magic Link. Se encontrado, os dados são vinculados a esse lead ao invés de criar um novo.

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/leads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "ML-20251030-143052-A8F3D-META",
    "contact": {
      "name": "João Silva",
      "phone": "+5511999999999"
    },
    "status": "in_progress",
    "notes": "Veio do WhatsApp com protocolo do Magic Link"
  }'

💡 Dica: Envie protocol + externalIdjuntos para garantir fallback caso o protocolo não seja encontrado.

PATCH/api/v1/integration/leads/:uuid/statusleads:write

Atualizar apenas o status do lead

Este endpoint aceita apenas o campo status. Para atualizar estimatedValue e saleDate, use POST /leads ou POST /sync com o mesmo externalId.

Bash

curl -X PATCH "https://dev-api-tools.helbioads.com/api/v1/integration/leads/abc12345-e5f6-7890-abcd-ef1234567890/status"   -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed_won"
  }'

POST${API_INTEGRATION_PATH}/leads/:id/interactionsinteractions:write

Adicionar interação ao lead

Body Parameters

Campo	Tipo	Descricao
`type`obrigatório	enum	NOTE, CALL, EMAIL, MEETING, COMMENT, TASK_CREATED, TASK_COMPLETED, CUSTOM
`title`	string	Título da interação
`description`	string	Descrição detalhada
`metadata`	object	Dados extras (duration, result, etc)

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/leads/clx123abc456/interactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CALL",
    "title": "Ligação de follow-up",
    "description": "Cliente interessado, agendou reunião",
    "metadata": {
      "duration": 480,
      "result": "positive"
    }
  }'

Próximos Passos

Contacts API

Gerenciar contatos

Conversations API

Gerenciar conversas