# Listar Leads

> Retorna a lista de leads da conta autenticada, com suporte a filtros.

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

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

## Requisição

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

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

### Query Parameters

- `startDate` (string, query):
  Data de início para filtrar leads pelo campo `createdAt`. Deve ser uma data válida no formato ISO 8601 (ex: `2025-01-01T00:00:00Z`). Utilizado em conjunto com `endDate`.

- `endDate` (string, query):
  Data de fim para filtrar leads pelo campo `createdAt`. Deve ser uma data válida no formato ISO 8601 (ex: `2025-12-31T23:59:59Z`). Utilizado em conjunto com `startDate`.

- `temperature` (number, query):
  Filtra leads pela temperatura: `1` (Frio), `2` (Morno) ou `3` (Quente).

- `source` (string, query):
  Filtra leads pela origem (ex: `site`, `instagram`, `indicacao`).

- `phone` (string, query):
  Filtra leads por número de telefone exato.

- `taxId` (string, query):
  Filtra leads por número de CPF ou CNPJ exato.

- `leadOwner` (string, query):
  Filtra leads pelo ID do usuário responsável pelo lead.

- `leadType` (string, query):
  Filtra leads pelo tipo (ex: `PF`, `PJ`).

- `labelId` (string, query):
  Filtra leads que possuem a etiqueta com o ID informado.

- `include` (string, query):
  Dados extras na resposta. Use `groups` para trazer os grupos de cada lead (`groups` e `company`). Sem este parâmetro a resposta não muda.

---

## Resposta

Retorna um array de objetos de lead. Os campos `accountId` e `updatedAt` são omitidos na resposta.

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

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

- `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 do lead.

- `zipCode` (string | null):
  CEP do endereço do lead.

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

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

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

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

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

- `complement` (string | null):
  Complemento do endereço.

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

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

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

- `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 `{}`.

- `groups` (array):
  Só com `?include=groups`. Grupos de que o lead é uma das pessoas: cada item traz `id`, `name` (o nome do grupo) e `role` (o cargo do lead nele).

- `company` (object | null):
  Só com `?include=groups`. Grupo de que o lead é a empresa, com `id`, `name` e `peopleCount` (quantidade de pessoas). `null` quando o lead não é a empresa de nenhum grupo.

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

- `status` (string):
  Status atual do lead. Padrão: `Lead`.

- `createdAt` (string):
  Data e horário de criação do lead (ISO 8601).

- `accountCRMLeadLabelAssignments` (array):
  Lista de etiquetas atribuídas ao lead.

  Propriedades da etiqueta:
  - `AccountLabel.id` (string):
  ID da etiqueta.
  
  - `AccountLabel.name` (string):
  Nome da etiqueta.
  
  - `AccountLabel.color` (string):
  Cor da etiqueta (hex ou nome).
  
  

- `accountExternalConversations` (array):
  Lista de conversas vinculadas ao lead (sem o conteúdo da última mensagem).

  Propriedades da Conversa:
  - `id` (string):
  Identificador único da conversa.
  
  - `contactName` (string):
  Nome do contato.
  
  - `contactPhone` (string | null):
  Telefone do contato.
  
  - `contactUsername` (string | null):
  Username do contato.
  
  - `status` (string):
  Status da conversa (`active`, `closed`, etc.).
  
  - `unreadCount` (number):
  Quantidade de mensagens não lidas.
  
  - `lastMessageAt` (string | null):
  Data e hora da última mensagem (ISO 8601).
  
  - `accountChatSectorId` (string | null):
  ID do setor do chat associado.
  
  - `conversationOwnerId` (string | null):
  ID do responsável pela conversa.
  
  - `createdAt` (string):
  Data de criação da conversa (ISO 8601).
  
  - `AccountChatSector` (object | null):
  Dados do setor da conversa (id, name, color).
  
  - `PlatformIntegration` (object | null):
  Dados da plataforma integrada (`name`).
  
  

---

## Exemplos

### Exemplo de requisição

```bash GET /api/v1/lead
curl --request GET \
  --url 'https://crm.wavups.com/api/v1/lead?startDate=2025-01-01T00:00:00Z&endDate=2025-12-31T23:59:59Z&source=instagram' \
  --header 'Token: SEU_TOKEN_DE_API'
```

### Exemplo de resposta

```json 200
[
  {
  "id": "clxyz1234",
  "leadOwner": "usr_abc",
  "name": "João Silva",
  "email": "joao@email.com",
  "phone": "5511999998888",
  "taxId": "12345678909",
  "source": "instagram",
  "profileImage": null,
  "zipCode": "01310-100",
  "state": "SP",
  "city": "São Paulo",
  "neighborhood": "Bela Vista",
  "streetAddress": "Av. Paulista",
  "number": "1000",
  "complement": "Apto 21",
  "country": "Brasil",
  "description": "Interesse em plano premium",
  "leadType": "PF",
  "leadTemperature": 2,
  "metadata": {
  "tags": ["premium", "interessado"],
  "custom_field": "valor customizado"
  },
  "utms": {
  "utm_source": "instagram",
  "utm_medium": "social",
  "utm_campaign": "campanha_junho"
  },
  "status": "Lead",
  "createdAt": "2025-06-15T14:30:00.000Z",
  "accountCRMLeadLabelAssignments": [
  {
  "AccountLabel": {
  "id": "lbl_001",
  "name": "Quente",
  "color": "#ef4444"
  }
  }
  ],
  "accountExternalConversations": [
  {
  "id": "clconv001",
  "contactName": "João Silva",
  "contactPhone": "5511999998888",
  "contactUsername": null,
  "status": "active",
  "unreadCount": 0,
  "lastMessageAt": "2025-06-15T15:00:00.000Z",
  "accountChatSectorId": "csector001",
  "conversationOwnerId": "usr_abc",
  "createdAt": "2025-06-15T14:30:00.000Z",
  "AccountChatSector": {
  "id": "csector001",
  "name": "Comercial",
  "color": "#3B82F6"
  },
  "PlatformIntegration": {
  "name": "WhatsApp Business"
  }
  }
  ]
  }
]
```

```json 500
{
  "error": "Error to get leads"
}
```