Leads

POST /leads — entrada de leads que cria empresa, contato e negócio em uma única chamada idempotente.

O endpoint de leads é a porta de entrada para formulários e landing pages. Em uma única chamada, o Vendee cria (ou reaproveita) empresa, contato e negócio e devolve os ids.

POST {BASE_URL}/api-v1-leads

Escopo necessário: leads:write.

Cada chamada cria ou reaproveita até três registros (empresa, contato e negócio). Use external_id para tornar reenvios idempotentes e veja Limites e boas práticas antes de gerar leads em alto volume.

Corpo da requisição

Campo	Tipo	Obrigatório	Notas
`first_name`	string	Sim	1–120 caracteres.
`last_name`	string	Não	Até 120 caracteres. Padrão: vazio.
`email`	string	Não	E-mail válido; normalizado para minúsculas.
`phone`	string	Não	Até 40 caracteres.
`company_name`	string	Não	1–255 caracteres. Cria/associa a empresa.
`external_id`	string	Não	1–255 caracteres. Chave de idempotência (veja abaixo).
`value`	number	Não	Valor do negócio (≥ 0).
`recurring_value`	number	Não	Valor recorrente/mensal (≥ 0).
`pipeline_id`	uuid	Não	Pipeline de destino. Omitido → pipeline padrão do workspace.
`stage_id`	uuid	Não	Etapa de destino. Omitido → primeira etapa do pipeline.
`owner_id`	uuid	Não	Responsável (id de membro). Omitido → resolução automática (veja abaixo).
`source`	string	Não	Origem do lead (ex.: "site"), até 120 caracteres.
`utm`	object	Não	`{ source, medium, campaign, term, content }`.
`custom_fields`	object	Não	Campos personalizados (≤ 50 chaves, ≤ 10 KB).

UTM achatado. Você também pode enviar utm_source, utm_medium, utm_campaign, utm_term, utm_content no nível raiz do corpo — eles são reagrupados dentro de utm automaticamente.

Exemplo

curl -X POST "{BASE_URL}/api-v1-leads" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Maria",
    "last_name": "Silva",
    "email": "[email protected]",
    "phone": "+55 11 99999-0000",
    "company_name": "Empresa Exemplo",
    "value": 12000,
    "recurring_value": 1000,
    "source": "site",
    "external_id": "form-123",
    "utm_source": "google",
    "utm_campaign": "institucional",
    "custom_fields": { "interesse": "Plano Pro" }
  }'

Resposta de sucesso

201 Created em uma criação nova; 200 OK quando a chamada é idempotente (mesmo external_id já processado):

{
  "lead": {
    "deal_id": "8f3c...",
    "contact_id": "1a2b...",
    "company_id": "9d8e...",
    "workspace_id": "44c1...",
    "status": "aberto",
    "pipeline_id": "7b6a...",
    "stage_id": "0f1e...",
    "owner_id": "3c2d...",
    "created_at": "2026-06-27T12:00:00.000Z"
  },
  "idempotent": false,
  "created": { "company": true, "contact": true, "deal": true }
}

company_id vem null quando o lead não traz company_name.
created indica o que foi efetivamente criado nesta chamada.

Idempotência

Se você enviar um external_id que já foi processado, a API não cria um segundo negócio: responde 200 OK com "idempotent": true e os ids do registro original. Isso torna seguro reenviar em caso de timeout de rede. Sem external_id, cada chamada cria um novo lead.

Resolução automática de responsável

Quando owner_id não é informado (ou aponta para alguém que não está no workspace), o Vendee escolhe o responsável nesta ordem:

O owner_id informado, se for um membro ativo do workspace.
O usuário que criou a API Key.
O membro de gestão (admin/gestor) ativo mais antigo do workspace.

Se nenhum se aplicar, a resposta é 422 owner_unresolved.

Erros possíveis

HTTP	`code`	Quando
`400`	`invalid_body`	Corpo ausente ou JSON inválido.
`401`	`missing_api_key` / `invalid_api_key` / `revoked_api_key`	Falha de autenticação.
`403`	`insufficient_scope`	A chave não tem `leads:write`.
`405`	`method_not_allowed`	Método diferente de `POST`.
`422`	`validation_error`	Algum campo inválido (vem com `details`).
`422`	`pipeline_not_found` / `no_default_pipeline`	Problema ao resolver o pipeline.
`422`	`stage_not_found` / `pipeline_has_no_stage`	Problema ao resolver a etapa.
`422`	`owner_unresolved`	Sem responsável ativo possível.
`500`	`internal_error`	Falha interna.

Veja todos em Erros.