Pular para o conteúdo

Leads, contas e cadências

Guia das rotas de CRM da API pública. Convenções gerais em Autenticação, Idempotência, Paginação e Erros.

Rota Acesso Para quê
POST /v1/inbound-submissions leads:write Uma pessoa pediu contato no seu site, app ou sistema (guia)
GET /v1/inbound-submissions/{id} leads:read Ler uma conversão
POST /v1/leads leads:write Mandar um lead novo do seu sistema
GET /v1/leads, GET /v1/leads/{id} leads:read Buscar por e-mail, telefone ou external_id, ou sincronizar
GET /v1/leads/{id}/activities leads:read Linha do tempo do lead
GET /v1/accounts, GET /v1/accounts/{id} accounts:read Etapa por funil, donos, qualificação, Cliente/Churn
GET /v1/funnels accounts:read Funis e etapas
GET /v1/cadences cadences:read Cadências que podem receber leads
POST /v1/leads/{id}/cadence-enrollments cadences:write Inscrever o lead numa cadência
POST /v1/leads/{id}/cadence-stop cadences:write Parar a cadência do lead
GET /v1/meetings, GET /v1/meetings/{id} meetings:read Reuniões marcadas

O lead entra como inbound: a configuração de Inbound do workspace decide a cadência, quem atende e quem é avisado, como num formulário do site.

Janela do terminal
curl https://api.preflow.sale/v1/leads \
-H "Authorization: Bearer $PREFLOW_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"Ana Souza","phone":"+5511999998888","email":"ana@empresa.com.br","company":"Empresa","external_id":"erp-12345"}'
{
"lead_id": "9b2c…",
"lead": { "id": "9b2c…", "object": "lead", "name": "Ana Souza", "status": "new", "origin": "inbound", "external_ids": ["erp-12345"], "…": "…" },
"created": true,
"matched_by": null,
"inbound_cadence": { "started": true, "reason": "distribution", "cadence_id": "4f1e…" }
}
  • Informe email ou phone (E.164, +5511999998888). Lead só com telefone é aceito.
  • O lead já existe? Se o e-mail ou o telefone já é de um lead do workspace, a resposta é 200 com created: false e esse lead, sem alterar nada nele. Lead que já está sendo trabalhado (em cadência, perdido, ganho ou que entrou por prospecção) nunca é reaberto, e inbound_cadence vem null.
  • A foto do lead (lead) só vem para chave que também tem leads:read. Uma chave só de escrita (um formulário, por exemplo) recebe só lead_id.
  • Limite próprio: 60 leads por minuto por chave.
  • external_id é o id do lead no seu sistema, único no workspace. Mandar o mesmo external_id de novo devolve o mesmo lead, sem alterar nada (matched_by: "external_id"). Dois pedidos ao mesmo tempo com o mesmo external_id nunca criam dois leads: o segundo recebe 409 external_id_in_progress e, tentando de novo, o lead do primeiro. Busque por ele com GET /v1/leads?external_id=erp-12345.
  • Contato que pediu para não ser contatado responde 422 lead_suppressed.
  • source é um rótulo livre do seu sistema (ex.: erp), guardado na entrada.
Janela do terminal
# por e-mail, telefone ou id do seu sistema
curl "https://api.preflow.sale/v1/leads?email=ana@empresa.com.br" -H "Authorization: Bearer $PREFLOW_API_KEY"
# sincronizar: tudo que mudou desde a última vez, página a página
curl "https://api.preflow.sale/v1/leads?updated_since=2026-11-16T00:00:00Z&limit=100" -H "Authorization: Bearer $PREFLOW_API_KEY"

A lista vem em ordem de atualização (a mais antiga primeiro). Guarde o updated_at do último item e use como updated_since na próxima rodada; o next_cursor leva à página seguinte da mesma rodada. Contas funcionam igual (GET /v1/accounts?updated_since=).

Para saber de mudança sem consultar, use os webhooks (seção Eventos abaixo).

GET /v1/leads/{id}/activities traz, do mais recente para o mais antigo, os toques e marcos do lead com um tipo público estável:

Tipo O que é
email.sent, email.received E-mail enviado ou recebido
whatsapp.sent, whatsapp.received WhatsApp enviado ou recebido
call.made, call.received Ligação feita ou recebida (call.connection_status)
linkedin.invitation_sent, linkedin.invitation_accepted, linkedin.sent, linkedin.received LinkedIn
meeting.scheduled, meeting.confirmed, meeting.completed Reunião
lead.lost, lead.reactivated, lead.status_changed Mudança de situação do lead
lead.received_from_api O lead chegou pela API
note Anotação

actor.type diz quem agiu: human, ai, lead, integration ou system. Registros internos do Preflow não aparecem.

A conta é a dona do lead. GET /v1/accounts/{id} traz:

  • funnels: uma entrada por funil, com a etapa fixa (new, qualified, scheduled, completed, no_show, negotiation, won, lost) e a etapa intermediária criada pelo workspace, quando houver.
  • owners.pre_sales e owners.sales: quem cuida da conta antes e depois da reunião.
  • qualification, is_customer (Cliente) e is_churn (Churn). Conta Churn sai do quadro (on_board: false em todos os funis); conta Cliente só fica em Vendas.

GET /v1/funnels lista os funis, as etapas fixas com o nome que aparece no Preflow e as etapas intermediárias de cada uma.

Janela do terminal
curl https://api.preflow.sale/v1/leads/9b2c…/cadence-enrollments \
-H "Authorization: Bearer $PREFLOW_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"cadence_id":"4f1e…"}'
  • A inscrição é a mesma da tela, com as mesmas recusas: lead já na cadência, pausa de engajamento, lead que passou por reunião, cooldown de perdido, cadência que nasceria toda cancelada. Cada uma tem um código em Erros.
  • Quem executa as etapas é o dono de pré-vendas da conta do lead. Na linha do tempo a inscrição aparece como feita pela integração, com a chave, e não conta como toque. A chave só inscreve enquanto quem a criou continua administrador ou dono do workspace.
  • POST /v1/leads/{id}/cadence-stop para a cadência deste lead: as outras pessoas da mesma conta seguem nas cadências delas, e conversa em andamento e follow-up marcado à mão continuam. O que estava na fila de envio é cancelado; o que o provedor já recebeu não volta. Sem cadência aberta, responde stopped: false.
Janela do terminal
curl "https://api.preflow.sale/v1/meetings?from=2026-11-01T00:00:00Z&to=2026-12-01T00:00:00Z&status=scheduled" \
-H "Authorization: Bearer $PREFLOW_API_KEY"
  • status: scheduled, confirmed, tentative, rescheduled, completed, no_show ou cancelled.
  • Bloqueios copiados da agenda do Outlook ou do Google não são reuniões e nunca aparecem.
  • closer é quem conduz a reunião; scheduled_by, quem marcou.

Para saber de mudança sem consultar, assine os eventos lead.*, account.* e meeting.* por webhook. O formato de cada um está em Eventos.