Leads

Criar Lead

Cria um novo lead para a conta autenticada.

POST/lead

curl --request POST \
  --url 'https://crm.wavups.com/api/v1/lead' \
  --header 'Token: SEU_TOKEN_DE_API' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Maria Souza",
    "email": "maria@email.com",
    "phone": "5511988887777",
    "taxId": "12345678909",
    "source": "site",
    "leadType": "PF",
    "leadTemperature": 3,
    "city": "Campinas",
    "state": "SP",
    "country": "brasil",
    "customFields": {
      "plano": "Ouro",
      "limite_de_credito": "1.500,50"
    },
    "utms": {
      "utm_source": "fb",
      "utm_medium": "paid",
      "utm_campaign": "120243645529690704",
      "utm_term": "120243645529720704",
      "utm_content": "120247590343130704"
    },
    "status": "Lead"
  }'

{
  "id": "clxyz5678",
  "leadOwner": null,
  "name": "Maria Souza",
  "email": "maria@email.com",
  "phone": "5511988887777",
  "taxId": "12345678909",
  "source": "site",
  "profileImage": null,
  "zipCode": null,
  "state": "SP",
  "city": "Campinas",
  "neighborhood": null,
  "streetAddress": null,
  "number": null,
  "complement": null,
  "country": "Brasil",
  "description": null,
  "leadType": "PF",
  "leadTemperature": 3,
  "metadata": null,
  "customFields": {
    "plano": "Ouro",
    "limite_de_credito": 1500.5
  },
  "utms": {
    "utm_source": "fb",
    "utm_medium": "paid",
    "utm_campaign": "120243645529690704",
    "utm_term": "120243645529720704",
    "utm_content": "120247590343130704"
  },
  "status": "Lead",
  "createdAt": "2025-06-15T14:30:00.000Z",
  "updatedAt": "2025-06-15T14:30:00.000Z"
}

Atribuição de Setor de Atendimento: Caso você deseje atribuir este lead a um setor de atendimento específico (ex: Vendas, Suporte), utilize o id retornado nesta criação para chamar o endpoint Criar Conversa informando o accountChatSectorId.

Leads duplicados: Se a conta já tem um lead com o mesmo CPF/CNPJ, telefone ou e-mail, nenhum lead novo é criado. A resposta traz o lead existente (mesmo formato, status 201), e os dados enviados só preenchem os campos que estavam vazios nele. Veja o Changelog.

Requisição

POST https://crm.wavups.com/api/v1/lead

Tokenstringobrigatório

Seu token de autenticação.

Body

namestringobrigatório

Nome do lead.

emailstring

E-mail do lead.

phonestring

Telefone do lead.

Padrão Estrito de Telefone (DDI + DDD + Número)

O número deve estar estritamente no formato de dígitos com DDI + DDD/Código de Área + Número (exemplo Brasil: 5547999999999, exemplo EUA: 14155552671), sem espaços, traços, parênteses ou o símbolo +.

Qualquer divergência neste formato causará falhas de envio na API do WhatsApp e duplicação de leads no sistema.

taxIdstring

CPF/CNPJ do lead.

sourcestring

Origem do lead (ex: site, instagram, indicacao).

leadOwnerstring

ID do vínculo do membro responsável pelo lead (campo id de Listar Membros da Conta). Precisa ser um membro desta conta; senão, 404.

profileImagestring

URL da imagem de perfil do lead.

zipCodestring

CEP do endereço do lead.

statestring

Estado do lead.

citystring

Cidade do lead.

neighborhoodstring

Bairro do lead.

streetAddressstring

Logradouro do lead.

numberstring

Número do endereço.

complementstring

Complemento do endereço.

countrystring

País do lead, em português (ex: Brasil, Portugal, Estados Unidos). Um nome da lista de países da plataforma é gravado com a grafia dela, sem diferenciar maiúsculas e acentos (brasil vira Brasil); outro texto é gravado como veio.

descriptionstring

Descrição ou observações sobre o lead.

leadTypestring

Tipo do lead (ex: PF, PJ).

leadTemperaturenumber

Temperatura do lead, em número inteiro. Um valor que não seja inteiro devolve 400.

metadataobject

Metadados adicionais do lead em formato JSON.

customFieldsobject

Campos personalizados do lead, pela chave do campo (veja a chave em Leads > Campos, na plataforma). Exemplo: { "plano": "Ouro", "limite_de_credito": "1.500,50" }.

Seleção: o nome ou o id da opção. Seleção múltipla: uma lista de nomes.
Número e moeda: 1500 ou 1.500,50. Data: 2026-03-15 ou 15/03/2026. Sim/Não: true/false ou sim/não.
Chave desconhecida ou valor inválido responde 400 e nada é gravado.
Campos obrigatórios da conta não são exigidos por esta API.

utmsobject

Parâmetros UTM associados ao lead em formato JSON. O objeto enviado deve conter as seguintes propriedades:

utm_source (string): Origem do tráfego (ex: fb, google, instagram).
utm_medium (string): Meio do tráfego (ex: paid, cpc, organic, story).
utm_campaign (string): Identificador ou nome da campanha (ex: 120243645529690704).
utm_term (string): Termo de pesquisa ou identificador de público/anúncio (ex: 120243645529720704).
utm_content (string): Conteúdo do anúncio ou identificador do criativo (ex: 120247590343130704).

Exemplo:

json

{
  "utm_source": "fb",
  "utm_medium": "paid",
  "utm_campaign": "120243645529690704",
  "utm_term": "120243645529720704",
  "utm_content": "120247590343130704"
}

statusstring

Status inicial do lead. Padrão: Lead.

Resposta

Retorna o objeto do lead criado com todos os campos, incluindo o accountId.

idstring

Identificador único do lead criado.

accountIdstring

ID da conta à qual o lead pertence.

leadOwnerstring | null

ID do usuário responsável.

namestring

Nome do lead.

emailstring | null

E-mail do lead.

phonestring | null

Telefone do lead.

taxIdstring | null

CPF/CNPJ do lead.

sourcestring | null

Origem do lead.

profileImagestring | null

URL da imagem de perfil.

zipCodestring | null

CEP.

statestring | null

Estado.

citystring | null

Cidade.

neighborhoodstring | null

Bairro.

streetAddressstring | null

Logradouro.

numberstring | null

Número do endereço.

complementstring | null

Complemento.

countrystring | null

País do lead, em português (ex: Brasil).

descriptionstring | null

Descrição ou observações.

leadTypestring | null

Tipo do lead.

leadTemperaturenumber | null

Temperatura do lead: 1 (Frio), 2 (Morno) ou 3 (Quente).

metadataobject | null

Metadados adicionais do lead em formato JSON.

customFieldsobject

Campos personalizados preenchidos do lead, pela chave do campo. Campos de seleção trazem o nome da opção e os de seleção múltipla uma lista de nomes. Campos sem valor não aparecem; sem nenhum, vem {}.

utmsobject | null

Parâmetros UTM associados ao lead em formato JSON.

statusstring

Status do lead.

createdAtstring

Data de criação (ISO 8601).

updatedAtstring

Data da última atualização (ISO 8601).

Autorização

Tokenstring · headerobrigatório

Token de autenticacao gerado na plataforma WavUps CRM.

Corpo da requisição

application/json · object

namestringobrigatório

Nome do lead.

emailstring

E-mail do lead.

phonestring

Telefone no formato internacional sem simbolos: 5547999999999 (pais + DDD + numero). Outros formatos causarao erros nos disparos via WhatsApp.

Exemplo: "5547999999999"

taxIdstring

CPF ou CNPJ do lead.

Exemplo: "12345678909"

sourcestring

Origem do lead (ex: site, instagram, indicacao).

leadOwnerstring

ID do usuario responsavel pelo lead.

profileImagestring

URL da imagem de perfil do lead.

zipCodestring

CEP do endereco.

statestring

Estado.

citystring

Cidade.

neighborhoodstring

Bairro.

streetAddressstring

Logradouro.

numberstring

Numero do endereco.

complementstring

Complemento do endereco.

countrystring

Pais do lead, em portugues (ex: Brasil, Portugal, Estados Unidos). Um nome da lista de paises da plataforma e gravado com a grafia dela, sem diferenciar maiusculas e acentos; outro texto e gravado como veio.

Exemplo: "Brasil"

descriptionstring

Descricao ou observacoes sobre o lead.

leadTypestring

Tipo do lead (ex: PF, PJ).

leadTemperatureenum<integer>

Temperatura do lead: 1 (Frio), 2 (Morno), 3 (Quente).

Valores aceitos: 1, 2, 3

statusstring

Status inicial do lead. Padrao: Lead.

metadataobject | null

Metadados adicionais do lead em formato JSON.

customFieldsobject

Campos personalizados do lead, pela chave do campo (a chave aparece em Leads > Campos, na plataforma). Seleção aceita o nome ou o id da opção; números aceitam `1500` ou `1.500,50`; datas, `2026-03-15` ou `15/03/2026`; Sim/Não, `true`/`false` ou `sim`/`não`. Chave desconhecida ou valor inválido responde `400` e nada é gravado. Na atualização, `null` ou texto vazio limpa o campo e os campos que não forem enviados ficam como estão.

Exemplo:

{
  "plano": "Ouro",
  "limite_de_credito": "1.500,50"
}

utmsobject | null

Parâmetros UTM associados ao lead em formato JSON.

Respostas

201application/json · object

Lead criado com sucesso.

idstring

leadOwnerstring | null

namestring

emailstring | null

phonestring | null

Telefone no formato 5547999999999 (pais + DDD + numero, sem espacos ou simbolos).

Exemplo: "5547999999999"

taxIdstring | null

CPF ou CNPJ do lead.

Exemplo: "12345678909"

sourcestring | null

profileImagestring | null

zipCodestring | null

statestring | null

citystring | null

neighborhoodstring | null

streetAddressstring | null

numberstring | null

complementstring | null

countrystring | null

Pais do lead, em portugues. Um nome da lista de paises da plataforma e gravado com a grafia dela (sem diferenciar maiusculas e acentos); outro texto e gravado como veio.

Exemplo: "Brasil"

descriptionstring | null

leadTypestring | null

leadTemperaturenumber | null

Temperatura do lead: 1 (Frio), 2 (Morno), 3 (Quente).

statusstring

metadataobject | null

Metadados adicionais do lead em formato JSON.

customFieldsobject

Campos personalizados do lead preenchidos, pela chave do campo. Campos de seleção trazem o nome da opção e os de seleção múltipla uma lista de nomes. Campos sem valor não aparecem.

Exemplo:

{
  "plano": "Ouro",
  "limite_de_credito": 1500,
  "cliente_vip": true
}

groupsobject[]

Só com `?include=groups`. Grupos de que o lead é uma das pessoas, com o cargo dele em cada um.

Exemplo:

[
  {
    "id": "cmg1grupo01",
    "name": "Acqua Distribuidora",
    "role": "Comprador"
  }
]

companyobject | null

Só com `?include=groups`. Grupo de que o lead é a empresa; `null` quando o lead não é empresa de nenhum grupo.

Exemplo:

{
  "id": "cmg1grupo01",
  "name": "Acqua Distribuidora",
  "peopleCount": 3
}

utmsobject | null

Parâmetros UTM associados ao lead em formato JSON.

createdAtstring<date-time>

accountExternalConversationsobject[]

Lista de conversas vinculadas ao lead.

500