Leads

Endpoints para criar, buscar, atualizar e mover leads (negócios) no funil, além de tags, sequências e envio de WhatsApp por lead.

Base URLhttps://app.syncro.chat/api/v1AuthX-API-Key: crm_SUA_CHAVE_AQUI

O objeto Lead

A maioria dos endpoints retorna o lead neste formato base (campos adicionais entram via ?include):

{
  "id": 123,
  "name": "João Silva",
  "phone": "+5511999887766",
  "email": "[email protected]",
  "company": "ACME",
  "birthday": "1990-01-15",
  "value": 5000.0,
  "source": "site",
  "tags": ["vip", "enterprise"],
  "pipeline_id": 1,
  "stage_id": 5,
  "notes": "Anotações do lead",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "verao_2026",
  "utm_term": null,
  "utm_content": null,
  "stage": { "id": 5, "name": "Proposta" },
  "pipeline": { "id": 1, "name": "Vendas" },
  "created_at": "2026-06-30T10:00:00Z",
  "custom_fields": { "tamanho_empresa": "100+" }
}

Listar leads

GET/leads

Permissão: leads:read

Lista os leads da conta, paginado, com filtros.

Parâmetros de query

pipeline_idintegeropcional

Filtra por pipeline

stage_idintegeropcional

Filtra por etapa

assigned_tointegeropcional

Filtra pelo ID do responsável

sourcestringopcional

Filtra pela origem

statusstringopcional

Filtra pelo status

tagsarrayopcional

Tags (nomes); retorna leads com **qualquer** uma

qstringopcional

Busca por nome, e-mail ou telefone

updated_sincedate (ISO 8601)opcional

Só leads alterados a partir desta data (ideal para sync)

created_fromdateopcional

Criados a partir de

created_todateopcional

Criados até

pageintegeropcional

Página (padrão 1)

per_pageintegeropcional

Itens por página (padrão 50, máx 200)

includestringopcional

Relações extras separadas por vírgula (ver abaixo)

Requisição

curl "https://app.syncro.chat/api/v1/leads?pipeline_id=1&per_page=2&include=owner" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Resposta

{
  "success": true,
  "data": [
    {
      "id": 123,
      "name": "João Silva",
      "phone": "+5511999887766",
      "email": "[email protected]",
      "company": "ACME",
      "value": 5000,
      "source": "site",
      "tags": [
        "vip"
      ],
      "pipeline_id": 1,
      "stage_id": 5,
      "stage": {
        "id": 5,
        "name": "Proposta"
      },
      "pipeline": {
        "id": 1,
        "name": "Vendas"
      },
      "created_at": "2026-06-30T10:00:00Z",
      "custom_fields": {},
      "assigned_to": 12,
      "owner": {
        "id": 12,
        "name": "Ana",
        "email": "[email protected]"
      }
    }
  ],
  "meta": {
    "total": 250,
    "per_page": 2,
    "current_page": 1,
    "last_page": 125,
    "has_more": true
  }
}

Criar lead

POST/leads

Permissão: leads:write

Cria um novo lead.

Parâmetros do body

namestringobrigatório

Nome do lead

pipeline_idintegerobrigatório

Pipeline de destino

stage_idintegerobrigatório

Etapa de destino

phonestringopcional

Telefone (E.164 recomendado)

emailstringopcional

E-mail

valuenumberopcional

Valor do negócio

sourcestringopcional

Origem

tagsarray(string)opcional

Criar ou atualizar lead (upsert)

POST/leads/upsert

Permissão: leads:write

Cria um lead novo ou atualiza um existente, casando por e-mail e/ou telefone. Ideal para sincronização. Aceita os mesmos campos de POST /leads, mais o campo abaixo.

Parâmetros do body

match_bystringopcional

email, phone ou email_or_phone (padrão email_or_phone)

É obrigatório enviar e-mail ou telefone (é a chave de match). Em update, só os campos enviados (não vazios) são alterados.

Requisição

curl -X POST "https://app.syncro.chat/api/v1/leads/upsert" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "[email protected]",
    "pipeline_id": 1,
    "stage_id": 5,
    "match_by": "email"
  }'

Resposta

{
  "success": true,
  "created": true,
  "lead": {
    "id": 123,
    "name": "João Silva",
    "stage_id": 5
  }
}

Buscar lead por ID

GET/leads/123

Permissão: leads:read

Retorna um lead. Aceita ?include= para carregar relações.

Requisição

curl "https://app.syncro.chat/api/v1/leads/123?include=owner%2Ctasks%2Cnotes" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Resposta

{
  "success": true,
  "lead": {
    "id": 123,
    "name": "João Silva",
    "stage_id": 5
  }
}

Mover lead de etapa

PUT/leads/123/stage

Permissão: leads:write

Move o lead para outra etapa (e pipeline).

Parâmetros do body

stage_idintegerobrigatório

Nova etapa

pipeline_idintegerobrigatório

Pipeline da etapa

Erros: 422 com blocked: true e pending_tasks se a etapa atual tem tarefas obrigatórias pendentes.

Requisição

curl -X PUT "https://app.syncro.chat/api/v1/leads/123/stage" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": 7,
    "pipeline_id": 1
  }'

Resposta

{
  "success": true,
  "lead_id": 123
}

Marcar como ganho

PUT/leads/123/won

Permissão: leads:write

Move o lead para uma etapa de ganho e registra a venda.

Parâmetros do body

stage_idintegerobrigatório

Etapa de ganho (deve ter is_won = true)

valuenumberopcional

Valor da venda (se omitido, usa o valor do lead)

Erros: 422 se a etapa não for de ganho ("A etapa informada não é uma etapa de ganho.") ou 422 blocked por tarefas obrigatórias pendentes.

Requisição

curl -X PUT "https://app.syncro.chat/api/v1/leads/123/won" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": 10,
    "value": 7500
  }'

Resposta

{
  "success": true,
  "lead_id": 123
}

Marcar como perdido

PUT/leads/123/lost

Permissão: leads:write

Move o lead para uma etapa de perda e registra o motivo.

Parâmetros do body

stage_idintegerobrigatório

Etapa de perda (deve ter is_lost = true)

reason_idintegeropcional

ID do motivo de perda (ver lost_reasons em [Pipelines](/pt-BR/pipelines))

Erros: 422 se a etapa não for de perda; 422 blocked por tarefas pendentes.

Requisição

curl -X PUT "https://app.syncro.chat/api/v1/leads/123/lost" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": 11,
    "reason_id": 3
  }'

Resposta

{
  "success": true,
  "lead_id": 123
}

Excluir lead

DELETE/leads/123

Permissão: leads:write

Remove o lead.

Requisição

curl -X DELETE "https://app.syncro.chat/api/v1/leads/123" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Resposta

{
  "success": true
}

Adicionar tags

POST/leads/123/tags

Permissão: leads:write

Adiciona tags ao lead (mantém as existentes).

Parâmetros do body

tagsarray(string)obrigatório

Nomes das tags (mín. 1)

Requisição

curl -X POST "https://app.syncro.chat/api/v1/leads/123/tags" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      "vip",
      "enterprise"
    ]
  }'

Resposta

{
  "success": true,
  "lead_id": 123,
  "tags": [
    "vip",
    "enterprise"
  ]
}

Remover uma tag

DELETE/leads/123/tags/vip

Permissão: leads:write

Remove uma tag pelo nome.

Requisição

curl -X DELETE "https://app.syncro.chat/api/v1/leads/123/tags/vip" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Resposta

{
  "success": true,
  "lead_id": 123,
  "tags": [
    "enterprise"
  ]
}

Inscrever em sequência de nutrição

POST/leads/123/enroll-sequence

Permissão: sequences:write

Inscreve o lead em uma sequência ativa. Veja a lista de sequências em Sequências.

Parâmetros do body

sequence_idintegerobrigatório

ID da sequência (deve estar ativa)

Requisição

curl -X POST "https://app.syncro.chat/api/v1/leads/123/enroll-sequence" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "sequence_id": 1
  }'

Resposta

{
  "success": true,
  "lead_id": 123,
  "sequence_id": 1,
  "lead_sequence_id": 45,
  "status": "active",
  "next_step_at": "2026-07-01T10:00:00Z"
}

Remover de sequência

DELETE/leads/123/enroll-sequence/1

Permissão: sequences:write

Tira o lead de uma sequência.

Requisição

curl -X DELETE "https://app.syncro.chat/api/v1/leads/123/enroll-sequence/1" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI"

Resposta

{
  "success": true,
  "lead_id": 123,
  "sequence_id": 1,
  "status": "exited_manual"
}

Enviar WhatsApp (texto ou imagem)

POST/leads/123/send-whatsapp

Permissão: whatsapp:write

Envia uma mensagem de texto ou imagem para o telefone do lead. Veja números conectados em WhatsApp.

Parâmetros do body

typestringobrigatório

text ou image

bodystringcondicional

Texto da mensagem (obrigatório se não houver media_url)

media_urlstring (URL)condicional

URL da imagem (obrigatório quando type=image)

captionstringopcional

Legenda da imagem

instance_idintegeropcional

Número a usar (se omitido, usa o principal)

Erros: 422 se o lead não tem telefone; 422 com skip_reason: "window_closed" em números da API Oficial fora da janela de 24h (use template); 502 em falha do provedor.

Requisição

curl -X POST "https://app.syncro.chat/api/v1/leads/123/send-whatsapp" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "body": "Olá! Tudo bem?",
    "instance_id": 1
  }'

Resposta

{
  "success": true,
  "conversation_id": 99,
  "message_id": 456,
  "provider_msg_id": "wamid.xyz123"
}

Enviar template (HSM)

POST/leads/123/send-whatsapp-template

Permissão: whatsapp:write

Envia um template oficial aprovado (necessário fora da janela de 24h na API Oficial). Veja templates em WhatsApp.

Parâmetros do body

template_idintegerobrigatório

ID do template (deve estar APPROVED)

variablesarray(string)opcional

Variáveis do corpo, na ordem

header_media_urlstring (URL)opcional

Mídia do cabeçalho, quando o template exige

instance_idintegeropcional

Número a usar

Requisição

curl -X POST "https://app.syncro.chat/api/v1/leads/123/send-whatsapp-template" \
  -H "X-API-Key: crm_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": 1,
    "variables": [
      "João",
      "Proposta",
      "30/07"
    ],
    "instance_id": 2
  }'

Resposta

{
  "success": true,
  "conversation_id": 99,
  "message_id": 457,
  "provider_msg_id": "wamid.xyz456",
  "template_name": "lembrete_proposta"
}

Relações extras (`?include`)

Em GET /leads e GET /leads/{id}, use ?include= com nomes separados por vírgula para carregar dados adicionais. Tokens desconhecidos são ignorados.

include	O que adiciona
`owner`	`assigned_to` (int) + `owner` `{id, name, email}`
`products`	`products[]` `{id, product_id, product_name, quantity, unit_price, discount_percent, total}`
`contacts`	`contacts[]` `{id, name, role, phone, email, is_primary}`
`notes`	`notes_list[]` `{id, body, author, created_at}`
`sales`	`sales[]` `{id, pipeline_id, value, closed_by, closed_at}` + `lost_sales[]` `{id, pipeline_id, reason_id, lost_at, lost_by}`
`tasks`	`tasks[]` `{id, subject, type, status, priority, due_date, due_time, completed_at, assigned_to}`
`sequences`	`active_sequence` `{id, name, current_step, total_steps, status}` + `sequences[]` `{id, sequence_id, name, status, next_step_at}`
`score`	`score` (int) + `score_updated_at`
`siblings`	`siblings[]` (outros negócios do mesmo contato) + `contact_totals`
`events`	`events[]` `{id, event_type, description, performed_by, created_at}`
`conversation`	`conversation` `{id, phone, status, last_message_at, unread_count, instance_id}`

events, conversation e siblings só estão disponíveis em GET /leads/{id} (não na listagem, por custo).