Entrada de lead

Porta de entrada de lead vindo de formulário, landing page ou anúncio. Cria contato, empresa e negócio numa tacada.

POST   {BASE_URL}/api-v1-leads  # cria

Use os endereços acima — são os que respondem hoje. A API está migrando para um endereço único ({BASE_URL}/api-v1/leads), que ainda não foi publicado: enquanto isso, qualquer chamada para ele devolve 404 not_found. Quando entrar no ar, esta página muda junto, e os endereços acima continuam valendo.

Escopo: leads:write.

Só POST — não existe listar nem detalhe. Contato, empresa e negócio são criados de uma vez: ou entra tudo, ou não entra nada. Permissão única: leads:write.

Campos

Campo	Tipo	Escrita	Notas
`external_id`	string	criar: opcional	De 1 a 255 caracteres.
`first_name`	string	criar: obrigatório	Campo montado pela API (não é coluna direta). de 1 a 120 caracteres.
`last_name`	string	criar: opcional	Campo montado pela API (não é coluna direta). máximo 120 caracteres; omitido → `""`.
`email`	string	criar: opcional	Campo montado pela API (não é coluna direta). formato email; máximo 255 caracteres; normalizado para minúsculas.
`phone`	string	criar: opcional	Campo montado pela API (não é coluna direta). máximo 40 caracteres.
`company_name`	string	criar: opcional	Campo montado pela API (não é coluna direta). de 1 a 255 caracteres.
`value`	number	criar: opcional	Mínimo 0.
`recurring_value`	number	criar: opcional	Mínimo 0.
`pipeline_id`	uuid	criar: opcional	Formato uuid; deve existir na ficha `pipelines`.
`stage_id`	uuid	criar: opcional	Formato uuid.
`owner_id`	uuid	criar: opcional	Formato uuid; deve existir na ficha `owners`.
`source`	string	criar: opcional	Máximo 120 caracteres.
`utm`	objeto	criar: opcional	Objeto {source, medium, campaign, term, content}. Campos chapados utm_source/utm_medium/... também são aceitos. Campo montado pela API (não é coluna direta).
`custom_fields`	objeto	criar: opcional, editar: sim	Objeto chave→valor. As chaves são as definidas na ficha `custom-fields`. até 50 chaves; até 10 KB; omitido → `{}`.

Criar

POST {BASE_URL}/api-v1-leads — escopo leads:write.

Campo	Tipo	Obrigatório	Notas
`external_id`	string	Não	De 1 a 255 caracteres.
`first_name`	string	Sim	Campo montado pela API (não é coluna direta). de 1 a 120 caracteres.
`last_name`	string	Não	Campo montado pela API (não é coluna direta). máximo 120 caracteres; omitido → `""`.
`email`	string	Não	Campo montado pela API (não é coluna direta). formato email; máximo 255 caracteres; normalizado para minúsculas.
`phone`	string	Não	Campo montado pela API (não é coluna direta). máximo 40 caracteres.
`company_name`	string	Não	Campo montado pela API (não é coluna direta). de 1 a 255 caracteres.
`value`	number	Não	Mínimo 0.
`recurring_value`	number	Não	Mínimo 0.
`pipeline_id`	uuid	Não	Formato uuid; deve existir na ficha `pipelines`.
`stage_id`	uuid	Não	Formato uuid.
`owner_id`	uuid	Não	Formato uuid; deve existir na ficha `owners`.
`source`	string	Não	Máximo 120 caracteres.
`utm`	objeto	Não	Objeto {source, medium, campaign, term, content}. Campos chapados utm_source/utm_medium/... também são aceitos. Campo montado pela API (não é coluna direta).
`custom_fields`	objeto	Não	Objeto chave→valor. As chaves são as definidas na ficha `custom-fields`. até 50 chaves; até 10 KB; omitido → `{}`.

curl -X POST "{BASE_URL}/api-v1-leads" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "..." }'

Webhooks desta ficha

lead.received

Formato do envio, cabeçalhos e verificação da assinatura em Webhooks.

Erros

HTTP	`code`	Quando
`401`	`missing_api_key` / `invalid_api_key` / `revoked_api_key`	Autenticação.
`403`	`insufficient_scope`	A chave não tem `leads:write`.
`422`	`validation_error`	Campo fora das regras da tabela acima.
`422`	`invalid_reference`	`pipeline_id`, `owner_id` aponta para fora deste cliente.
`405`	`method_not_allowed`	Método não suportado neste endereço.
`500`	`internal_error`	Falha interna.

Catálogo completo em Erros.

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 específicos desta ficha

HTTP	`code`	Quando
`400`	`invalid_body`	Corpo ausente ou JSON inválido.
`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.

Veja todos em Erros.

Entrada de lead

Nesta página