# Listar contatos com paginação

`POST /contacts/list`

Pasta: **Contatos**

## Autenticação

```http
token: {{token}}
```

## Descrição

# Listar contatos com paginação

Lista contatos com controle de `limit` e `offset`. Use em CRMs, tabelas e bases grandes em que `GET /contacts` não basta.

## Endpoint

`POST {{baseUrl}}/contacts/list`

## Autenticação

Envie o token da instância no header `token: {{token}}`.

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `limit` | integer | Não | Máximo de itens por página. Padrão: `100`. Máximo: `1000`. |
| `offset` | integer | Não | Quantos itens pular. Padrão: `0`. |
| `contactScope` | string | Não | Escopo: `address_book` (padrão se vazio/inválido), `outside_address_book` ou `all`. |

## Exemplo de Requisição

```bash
curl --request POST '{{baseUrl}}/contacts/list' \
  --header 'token: {{token}}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "limit": 100,
  "offset": 0,
  "contactScope": "address_book"
}'
```

## Resposta de Sucesso

```json
{
  "success": true,
  "contacts": [
    {
      "jid": "5511999999999@s.whatsapp.net",
      "contact_name": "João Silva",
      "contact_FirstName": "João"
    }
  ],
  "totalDeviceContacts": 2450,
  "pagination": {
    "totalRecords": 2450,
    "limit": 100,
    "offset": 0
  }
}
```

## Erros comuns

- `401 Unauthorized`: token ausente ou inválido.
- `500 Internal Server Error`: instância desconectada ou falha ao ler contatos.

## Observações

- Diferente de `GET /contacts`, esta rota devolve metadados de paginação.
- Para a próxima página, some `offset += limit`.

## Corpo (exemplo)

```json
{
  "limit": 100,
  "offset": 0,
  "contactScope": "address_book"
}
```

## cURL

```bash
curl -X POST "{{baseUrl}}/contacts/list" \
  -H "token: {{token}}" \
  -H "Content-Type: application/json" \
  -d '{
  "limit": 100,
  "offset": 0,
  "contactScope": "address_book"
}'
```

---

[Índice da pasta](./index.md) · [Índice geral](../index.md) · [UI](https://gozap.dev/docs?op=contatos/listar-contatos-com-paginacao)