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

O que continua no endereço antigo. POST {BASE_URL}/api-v1-leads só atende neste endereço — no endereço novo ({BASE_URL}/api-v1/leads) essa chamada devolve 405 method_not_allowed.

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. Em workspace que usa a camada de leads, nasce um lead (não um negócio) e a resposta traz lead_id, idempotent e open_deal_id (negócio aberto da mesma empresa, só informativo).

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.
`cnpj`	string	criar: opcional	Só vale quando o workspace usa a camada de leads: a empresa é reaproveitada pelo CNPJ (só dígitos). Campo montado pela API (não é coluna direta). máximo 32 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.
`cnpj`	string	Não	Só vale quando o workspace usa a camada de leads: a empresa é reaproveitada pelo CNPJ (só dígitos). Campo montado pela API (não é coluna direta). máximo 32 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 → `{}`.

Além de first_name, informe ao menos um entre email, phone ou a empresa (company_name ou cnpj). Sem nenhum deles a resposta é 422 validation_error.

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.

Origem do lead (`source`)

O source é casado com as origens que já existem no workspace sem diferenciar maiúsculas nem espaços nas pontas: "Site", " site " e "SITE" caem na mesma origem. Se ela estiver arquivada, volta a ficar ativa. Se nenhuma origem tiver esse nome, a API cria a origem com o nome enviado (sem os espaços das pontas, até 120 caracteres). Assim cada campanha pode mandar o próprio nome sem cadastro prévio.

Reaproveitamento de contato sem e-mail, pelo telefone

Quando o lead não traz email, a API tenta casar o phone com um contato que já existe neste workspace antes de criar um novo. A comparação ignora formatação — DDD com ou sem parênteses, hífen, espaço, com ou sem o DDI +55 casam entre si. O contato encontrado não é alterado (nome, empresa e telefone continuam como estavam); o lead novo só se liga a ele, e created.contact vem false.

Com email informado o comportamento não muda: o casamento continua sendo só por e-mail, mesmo que ele não encontre ninguém — não cai para o telefone.

Limite conhecido: um celular brasileiro com e sem o nono dígito ((48) 99999-0000 × (48) 9999-0000) é tratado como dois números diferentes — não gera reaproveitamento entre eles.

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