API de contatos, negócios e jornadas

Estes endpoints deixam o seu próprio código, o Zapier ou o n8n agirem na sua conta: adicionar contatos, abrir e mover negócios, inscrever contatos em jornadas e ler os identificadores de que essas chamadas precisam. Eles usam a mesma chave de API da API de envio.

Authorization: Bearer mia_live_...

Cada família de endpoints aceita 60 requisições por minuto por chave. Acima disso, você recebe 429. Erros voltam como {"error": "…"} com um status 4xx. O contrato completo, com cada formato de resposta, está na especificação OpenAPI.

Contatos

Criar ou atualizar

POST /api/v1/contacts adiciona um endereço a uma lista de contatos, ou o atualiza se ele já estiver lá:

{
  "listId": "list_abc123",
  "email": "[email protected]",
  "fields": { "first_name": "Ada", "company": "Analytical Engines" }
}

A resposta é 201 para um contato novo e 200 para uma atualização, com o contato salvo. Para enviar até 500 de uma vez, use {"listId": "…", "contacts": [{"email": "…", "first_name": "…"}, …]}, que responde com contagens.

Cada endereço é verificado ao ser salvo. A API nunca registra uma resposta de consentimento, então esses contatos recebem envios como antes. Um contato individual que faria a lista passar do limite de contatos do seu plano recebe 409.

Buscar

GET /api/v1/[email protected] devolve o contato desse endereço em cada lista, do mais recente para o mais antigo. Adicione &listId= para buscar em uma lista só. Cada busca fica registrada no log de acesso a dados pessoais da sua conta, como um contato visto no painel.

Listas

GET /api/v1/lists devolve id, name, fields e rowCount de cada lista de contatos. Nenhum dado de contato.

Negócios

Criar

POST /api/v1/deals:

{
  "email": "[email protected]",
  "title": "Annual plan",
  "value": 1200,
  "currency": "BRL"
}

Indique o contato com email, ou com listId mais rowId. Só com o e-mail, o negócio vai para a lista atualizada mais recentemente que tem o endereço. Sem pipelineId e stageId, ele entra na primeira etapa aberta do seu pipeline padrão. currency é USD por padrão.

Envie um cabeçalho Idempotency-Key (um número de pedido, por exemplo) para tornar as novas tentativas seguras. Uma repetição com a mesma chave responde 200 com "created": false em vez de criar um segundo negócio.

Atualizar ou mover

PATCH /api/v1/deals/{id} aceita title, value, currency e stageId. Mover para uma etapa ganha ou perdida fecha o negócio. O corpo inteiro é validado antes, então uma etapa desconhecida não muda nada. Uma movimentação dispara o gatilho de jornada Mudança de etapa do negócio e o webhook deal.stage_changed, igual a uma movimentação no quadro.

Pipelines

GET /api/v1/pipelines devolve os seus pipelines, o padrão primeiro, cada um com as suas etapas (id, name, kind). Use para encontrar o stageId para onde mover um negócio.

Jornadas

GET /api/v1/journeys lista as suas jornadas com identificador, nome, gatilho e se estão ativas. ?trigger=api devolve só aquelas em que o seu código pode inscrever contatos.

POST /api/v1/journeys/{id}/trigger com {"email": "…", "listId": "…"} inscreve um contato em uma jornada cujo gatilho é Chamada de API. Veja jornadas.

Eventos de exemplo

GET /api/v1/events/sample?type=deal.stage_changed devolve {"events": [ … ]} com um envelope de webhook de exemplo desse tipo, ou um de cada tipo sem type. Ferramentas de automação usam isso para mostrar os campos antes de chegar um evento real.

Webhooks

GET, POST /api/v1/webhooks e DELETE /api/v1/webhooks/{id} gerenciam as assinaturas de eventos. Veja webhooks e eventos.