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 |
Criar lead
Seção intitulada “Criar lead”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.
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
emailouphone(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 é
200comcreated: falsee 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, einbound_cadencevemnull. - A foto do lead (
lead) só vem para chave que também temleads: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 mesmoexternal_idde novo devolve o mesmo lead, sem alterar nada (matched_by: "external_id"). Dois pedidos ao mesmo tempo com o mesmoexternal_idnunca criam dois leads: o segundo recebe409 external_id_in_progresse, tentando de novo, o lead do primeiro. Busque por ele comGET /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.
Buscar e sincronizar
Seção intitulada “Buscar e sincronizar”# por e-mail, telefone ou id do seu sistemacurl "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áginacurl "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).
Linha do tempo
Seção intitulada “Linha do tempo”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 |
|
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.
Contas e funis
Seção intitulada “Contas e funis”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_saleseowners.sales: quem cuida da conta antes e depois da reunião.qualification,is_customer(Cliente) eis_churn(Churn). Conta Churn sai do quadro (on_board: falseem 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.
Cadências
Seção intitulada “Cadências”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-stoppara 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, respondestopped: false.
Reuniões
Seção intitulada “Reuniões”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_showoucancelled.- 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.
Eventos
Seção intitulada “Eventos”Para saber de mudança sem consultar, assine os eventos lead.*, account.* e
meeting.* por webhook. O formato de cada um está em
Eventos.