Referência: criar lead (POST /api/leads)

Atualizado em 03/07/2026

Cria um lead na imobiliária informada. O lead entra na roleta, notifica os corretores e chega com a origem completa.

POST https://crm.hediz.com/api/leads
Content-Type: application/json

Campos do corpo (JSON)

Obrigatórios

Campo	Tipo	Descrição
`imobiliaria_slug`	string	O identificador da sua conta (o mesmo da URL do seu CRM: `crm.hediz.com/SEU-SLUG/...`).
`nome`	string	Nome do lead (mínimo 2 caracteres).
`whatsapp`	string	Telefone com DDD (mínimo 10 dígitos).

Opcionais, contato e conteúdo

Campo	Tipo	Descrição
`email`	string	E-mail válido.
`respostas`	objeto	Respostas do seu formulário (chave/valor livre). Ficam salvas no lead.

Opcionais, vínculo com imóvel

Campo	Tipo	Descrição
`imovel_id`	uuid	ID interno do imóvel no CRM.
`imovel_codigo`	string	Ou o código de referência do imóvel (mais prático). O CRM resolve sozinho.

Opcionais, atribuição de marketing

Campo	Tipo	Descrição
`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`	string	UTMs da visita. Convenção: `utm_content` com o ID do anúncio Meta faz o CRM vincular o lead à campanha/conjunto/anúncio automaticamente.
`fbclid`, `fbp`, `fbc`	string	Cookies/parâmetros do Meta pra atribuição e API de conversões.
`event_source_url`	string	URL da página onde o lead converteu.
`creative_code`	string	Código do criativo (query `?creative=` dos seus anúncios).
`lp_id`	uuid	Variante de landing page (teste A/B).

Exemplo: curl

curl -X POST https://crm.hediz.com/api/leads \
  -H "Content-Type: application/json" \
  -d '{
    "imobiliaria_slug": "sua-imobiliaria",
    "nome": "Maria Silva",
    "whatsapp": "11999998888",
    "email": "maria@email.com",
    "imovel_codigo": "AP-102",
    "utm_source": "site",
    "utm_campaign": "lancamento-jardins",
    "respostas": { "renda": "8 a 12 mil", "entrada": "100 mil" }
  }'

Exemplo: JavaScript (formulário do seu site)

await fetch("https://crm.hediz.com/api/leads", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    imobiliaria_slug: "sua-imobiliaria",
    nome: form.nome,
    whatsapp: form.whatsapp,
    email: form.email,
    imovel_codigo: "AP-102",
    utm_source: new URLSearchParams(location.search).get("utm_source") ?? undefined,
    event_source_url: location.href,
  }),
});

Respostas

Código	Significado
`200`	Lead criado. O corpo retorna os dados do lead.
`400`	Corpo inválido (o retorno detalha o campo com problema).
`404`	`imobiliaria_slug` não encontrado ou conta inativa.
`429`	Rate limit excedido (30/min por IP, 200/min por conta). Tente de novo em instantes.
`500`	Erro interno; tente novamente.

Boas práticas

Envie o whatsapp com DDD; o CRM normaliza o formato.
Prefira imovel_codigo a imovel_id (não muda entre ambientes e é visível na tela de Imóveis).
Repasse as UTMs reais da sessão do visitante pra atribuição funcionar de ponta a ponta.
Leads duplicados: o CRM não bloqueia duplicados vindos da API; se o seu formulário permite reenvio, trate no seu lado ou deixe que a equipe use o fluxo de enriquecimento.