# Criar Lead

> Cria um novo lead para a conta autenticada.

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

Página: https://crm.wavups.com/docs/api/leads/criar

**Nota:**
  **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](https://crm.wavups.com/docs/api/conversas/criar) informando o `accountChatSectorId`.

**Nota:**
  **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](https://crm.wavups.com/docs/api/changelog).

## Requisição

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

- `Token` (string, obrigatório, header):
  Seu token de autenticação.

### Body

- `name` (string, obrigatório, body):
  Nome do lead.

- `email` (string, body):
  E-mail do lead.

- `phone` (string, body):
  Telefone do lead.

  **Atenção:**
  **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.
  

- `taxId` (string, body):
  CPF/CNPJ do lead.

- `source` (string, body):
  Origem do lead (ex: `site`, `instagram`, `indicacao`).

- `leadOwner` (string, body):
  ID do vínculo do membro responsável pelo lead (campo `id` de [Listar Membros da Conta](https://crm.wavups.com/docs/api/membros/listar)). Precisa ser um membro desta conta; senão, `404`.

- `profileImage` (string, body):
  URL da imagem de perfil do lead.

- `zipCode` (string, body):
  CEP do endereço do lead.

- `state` (string, body):
  Estado do lead.

- `city` (string, body):
  Cidade do lead.

- `neighborhood` (string, body):
  Bairro do lead.

- `streetAddress` (string, body):
  Logradouro do lead.

- `number` (string, body):
  Número do endereço.

- `complement` (string, body):
  Complemento do endereço.

- `country` (string, body):
  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.

- `description` (string, body):
  Descrição ou observações sobre o lead.

- `leadType` (string, body):
  Tipo do lead (ex: `PF`, `PJ`).

- `leadTemperature` (number, body):
  Temperatura do lead, em número inteiro. Um valor que não seja inteiro devolve 400.

- `metadata` (object, body):
  Metadados adicionais do lead em formato JSON.

- `customFields` (object, body):
  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.

- `utms` (object, body):
  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"
  }
  ```

- `status` (string, body):
  Status inicial do lead. Padrão: `Lead`.

---

## Resposta

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

- `id` (string):
  Identificador único do lead criado.

- `accountId` (string):
  ID da conta à qual o lead pertence.

- `leadOwner` (string | null):
  ID do usuário responsável.

- `name` (string):
  Nome do lead.

- `email` (string | null):
  E-mail do lead.

- `phone` (string | null):
  Telefone do lead.

- `taxId` (string | null):
  CPF/CNPJ do lead.

- `source` (string | null):
  Origem do lead.

- `profileImage` (string | null):
  URL da imagem de perfil.

- `zipCode` (string | null):
  CEP.

- `state` (string | null):
  Estado.

- `city` (string | null):
  Cidade.

- `neighborhood` (string | null):
  Bairro.

- `streetAddress` (string | null):
  Logradouro.

- `number` (string | null):
  Número do endereço.

- `complement` (string | null):
  Complemento.

- `country` (string | null):
  País do lead, em português (ex: `Brasil`).

- `description` (string | null):
  Descrição ou observações.

- `leadType` (string | null):
  Tipo do lead.

- `leadTemperature` (number | null):
  Temperatura do lead: `1` (Frio), `2` (Morno) ou `3` (Quente).

- `metadata` (object | null):
  Metadados adicionais do lead em formato JSON.

- `customFields` (object):
  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 `{}`.

- `utms` (object | null):
  Parâmetros UTM associados ao lead em formato JSON.

- `status` (string):
  Status do lead.

- `createdAt` (string):
  Data de criação (ISO 8601).

- `updatedAt` (string):
  Data da última atualização (ISO 8601).

---

## Exemplos

### Exemplo de requisição

```bash POST /api/v1/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"
  }'
```

### Exemplo de resposta

```json 201
{
  "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"
}
```

```json 500
{
  "error": "Error to create lead"
}
```