Leads API

Leia leads e atualize o status deles a partir dos seus próprios sistemas com uma chave de API com escopo.

Esta página foi traduzida do inglês. Se houver qualquer diferença, vale a versão em inglês. Ler em inglês

A Leads API permite que o seu CRM, data warehouse ou automação leia os seus leads e atualize o status deles.

Chaves

Crie chaves no Studio em Integrations → Leads API → New key. Cada chave tem:

um nome;
permissões: leads:read (Read leads) e, opcionalmente, leads:write-status (Change lead status);
uma validade de 30, 90, 180 dias ou 1 ano.

As chaves têm o formato atl_lead_ seguido de 43 caracteres. Elas são mostradas uma única vez, armazenadas apenas como uma impressão digital (fingerprint), verificadas a cada requisição e podem ser revogadas a qualquer momento (Revoke key). Um ambiente de site pode ter até 20 chaves ativas. Criar uma chave pode exigir uma segunda confirmação no seu celular.

URL base e autenticação

https://<delivery host>/v1/leads-api/environments/{environmentId}
Authorization: Bearer atl_lead_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

As respostas têm Cache-Control: private, no-store. Os erros usam o formato application/problem+json da RFC 9457.

Liste leads

GET /leads?since=2026-10-01T00:00:00Z&limit=50&cursor=…

Parâmetro	Observações
`since`	Somente leads atualizados nesse momento ou depois. ISO 8601 com fuso horário
`limit`	De 1 a 200, padrão 50
`cursor`	O `nextCursor` da resposta anterior

Os leads vêm começando pela alteração mais antiga. A resposta é { "leads": [ … ], "nextCursor": "…" | null }. Continue paginando até nextCursor ser null e guarde o último updatedAt para buscar apenas as alterações da próxima vez.

A lista inclui leads mesclados, anonimizados e de teste. Verifique mergedInto, anonymisedAt e isTest.

Obtenha um lead

GET /leads/{leadId}

Campo	Observações
`id`, `source`	A origem é o formulário ou chatbot de onde o lead veio
`form`	`{ key, name }`, ou `null` para leads de chatbot
`name`, `email`, `phone`, `company`, `message`	Vazios depois que a retenção removeu os dados pessoais
`details`	Quaisquer outras respostas
`status`	`new`, `contacted`, `qualified`, `won`, `lost` ou `spam`
`isTest`	Envios de teste do Studio
`version`	Envie-o de volta ao alterar o status
`mergedInto`, `anonymisedAt`	Definidos quando o lead foi mesclado ou anonimizado
`createdAt`, `updatedAt`	Timestamps ISO 8601

Altere o status de um lead

PATCH /leads/{leadId}/status com { "status": "qualified", "expectedVersion": 4 }. Exige a permissão Change lead status. A alteração aparece no histórico do lead como feita pela chave.

Erros e limites

Status	Código	Significado
401	`CP_UNAUTHENTICATED`	Chave ausente, incorreta, expirada ou revogada
403	`CP_FORBIDDEN`	A chave não tem a permissão para esta requisição
404	`CP_NOT_FOUND`	Não existe esse lead neste ambiente
409	`CP_VERSION_CONFLICT`	O lead mudou desde que você o leu. Leia-o novamente
422	`REQUEST_SCHEMA_INVALID`	O corpo da requisição ou um parâmetro não é válido
422	`CURSOR_INVALID`	Não foi possível ler o cursor
429	`RATE_LIMITED`	Mais de 300 requisições por minuto. Aguarde e tente novamente

O limite de taxa é aplicado por servidor de API do Atlas, então trate 300 requisições por minuto como um teto, não como uma garantia.