> For the complete documentation index, see [llms.txt](https://ajuda.livechat360.com.br/crm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.livechat360.com.br/crm/api-docs/contatos.md).

# Contatos

Os contatos (leads) da conta: dados cadastrais, endereço, tags e campos personalizados.

| Método | Rota                          | Operação |
| ------ | ----------------------------- | -------- |
| GET    | `/v1/leads`, `/v1/leads/{id}` | `read`   |
| POST   | `/v1/leads`                   | `insert` |
| PUT    | `/v1/leads/{id}`              | `update` |
| DELETE | `/v1/leads/{id}`              | `delete` |

## Filtros

| Parâmetro                                          | Comportamento                                                                                                                                        |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                                             | exato (sem diferenciar maiúsculas) no nome de exibição; `name__contains` para parcial                                                                |
| `phone`                                            | encontra as variações brasileiras do número (com/sem `55`, com/sem o nono dígito; o prefixo `+` é aceito, mas deve ser codificado como `%2B` na URL) |
| `email`                                            | exato, sem diferenciar maiúsculas                                                                                                                    |
| `cpf`                                              | parcial, ignora pontuação                                                                                                                            |
| `cnpj`                                             | exato, aceita o valor com ou sem máscara                                                                                                             |
| `client_code`                                      | exato                                                                                                                                                |
| `company_id`                                       | inteiro ou lista separada por vírgula (contatos vinculados a qualquer uma das empresas)                                                              |
| `created_at__gte/__lte/__gt/__lt`, `updated_at__…` | comparação ISO 8601                                                                                                                                  |
| `custom__<nome do campo>`                          | igualdade em campo personalizado; o nome é a mesma chave exibida em `custom_fields` (codifique espaços na URL)                                       |

**Ordenação:** `name`, `created_at`, `updated_at` (padrão `-created_at`).

```bash
curl -H "Authorization: Bearer $KEY" "https://app-api.atendeserver.com.br/v1/leads?page=2&per_page=10&sort=-updated_at"
curl -H "Authorization: Bearer $KEY" "https://app-api.atendeserver.com.br/v1/leads?name__contains=maria&company_id=87&created_at__gte=2026-01-01"
curl -H "Authorization: Bearer $KEY" "https://app-api.atendeserver.com.br/v1/leads?custom__erp_id=9981"
curl -H "Authorization: Bearer $KEY" "https://app-api.atendeserver.com.br/v1/leads/4521"
```

## Payload

```json
{
  "data": {
    "id": 4521,
    "name": "Maria Souza",
    "phone": "5511999998888",
    "email": "maria@email.com",
    "cpf": "39053344705",
    "cnpj": null,
    "rg": null,
    "client_code": "C-1042",
    "birth_date": "1990-04-12",
    "occupation": "Designer",
    "address": "Rua das Flores",
    "address_number": "120",
    "address_complement": "Sala 3",
    "address_neighbourhood": "Centro",
    "address_city": "Londrina",
    "address_uf": "PR",
    "address_zip_code": "86000000",
    "tags": ["vip", "newsletter"],
    "company_id": 87,
    "custom_fields": { "erp_id": "9981" },
    "created_at": "2026-01-10T12:00:00.000Z",
    "updated_at": "2026-06-20T16:30:00.000Z"
  }
}
```

`company_id` é a empresa vinculada mais antiga (ou `null`); `custom_fields` é um objeto com o nome de cada campo personalizado preenchido.

## Escrita

| Campo                                                          | Tipo               | Observações                                                                                                                                                                                               |
| -------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                                                         | string             | **obrigatório no POST**                                                                                                                                                                                   |
| `phone`                                                        | string             | **obrigatório no POST**; normalizado para dígitos (10 a 15, incluindo DDI e DDD); telefone já cadastrado retorna 422; no PUT, o telefone de contatos com conversa de WhatsApp não pode ser alterado (422) |
| `email`, `rg`, `client_code`, `occupation`, campos de endereço | string, anulável   | `address_uf` é convertido para maiúsculas; `cpf`/`cnpj`/`address_zip_code` são armazenados sem máscara                                                                                                    |
| `birth_date`                                                   | data ISO, anulável |                                                                                                                                                                                                           |
| `tags`                                                         | string\[]          | **substitui** o conjunto de tags; nomes inexistentes são criados                                                                                                                                          |
| `company_id`                                                   | inteiro, anulável  | a empresa deve existir; **substitui** o vínculo (`null` desvincula)                                                                                                                                       |
| `custom_fields`                                                | objeto             | **mesclagem**; chaves = nomes dos campos personalizados; chave desconhecida retorna 422                                                                                                                   |

Contatos criados pela API ficam imediatamente disponíveis no painel, inclusive na caixa de conversas.

{% hint style="danger" %}
A exclusão (`DELETE`) remove o contato das listagens e encerra os atendimentos em aberto; as negociações de que ele participava recebem uma anotação registrando a exclusão. Contatos bloqueados não podem ser excluídos (422).
{% endhint %}

```bash
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name":"Maria Souza","phone":"5511999998888","email":"maria@email.com","tags":["vip"],"custom_fields":{"erp_id":"9981"}}' \
  "https://app-api.atendeserver.com.br/v1/leads"

curl -X PUT -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"occupation":"Designer","company_id":87,"custom_fields":{"erp_id":null}}' \
  "https://app-api.atendeserver.com.br/v1/leads/4521"

curl -X DELETE -H "Authorization: Bearer $KEY" "https://app-api.atendeserver.com.br/v1/leads/4521"
```