> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mycentralino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lista Contatti

> Ottieni i contatti della rubrica con ricerca e paginazione

# GET /v1/contacts

Restituisce i contatti della rubrica del tuo centralino. Supporta ricerca e paginazione.

<Note>
  La rubrica è la stessa usata dal centralino per il **riconoscimento del chiamante**: i contatti gestiti via API vengono mostrati automaticamente durante le chiamate.
</Note>

## Parametri Query

| Parametro | Tipo   | Default | Descrizione                       |
| --------- | ------ | ------- | --------------------------------- |
| `page`    | int    | `1`     | Pagina da visualizzare            |
| `limit`   | int    | `200`   | Contatti per pagina (max `500`)   |
| `search`  | string | —       | Filtra per numero, nome o azienda |

## Richiesta

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.mycentralino.com/v1/contacts?page=1&limit=200&search=rossi" \
    -H "X-API-KEY: sk_mycentralino_your_api_key"
  ```

  ```php PHP theme={null}
  <?php
  $params = http_build_query(['page' => 1, 'limit' => 200, 'search' => 'rossi']);
  $ch = curl_init("https://api.mycentralino.com/v1/contacts?{$params}");
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          'X-API-KEY: sk_mycentralino_your_api_key'
      ]
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  print_r(json_decode($response, true));
  ```

  ```python Python theme={null}
  import requests

  headers = {'X-API-KEY': 'sk_mycentralino_your_api_key'}
  params = {'page': 1, 'limit': 200, 'search': 'rossi'}

  response = requests.get(
      'https://api.mycentralino.com/v1/contacts',
      headers=headers,
      params=params
  )
  print(response.json())
  ```
</CodeGroup>

## Risposta

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 12345,
      "number": "3331234567",
      "name": "Mario Rossi",
      "company": "ACME S.r.l.",
      "notes": "Cliente principale"
    },
    {
      "id": 12346,
      "number": "0686858483",
      "name": "Anna Bianchi",
      "company": null,
      "notes": null
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_contacts": 2,
    "per_page": 200,
    "showing_from": 1,
    "showing_to": 2
  },
  "limit": {
    "max": 4000,
    "used": 2,
    "remaining": 3998
  },
  "filters": {
    "search": "rossi"
  }
}
```

## Campi Risposta

| Campo     | Tipo           | Descrizione             |
| --------- | -------------- | ----------------------- |
| `id`      | int            | ID univoco del contatto |
| `number`  | string         | Numero di telefono      |
| `name`    | string         | Nome del contatto       |
| `company` | string \| null | Azienda (opzionale)     |
| `notes`   | string \| null | Note (opzionale)        |

### Oggetto pagination

| Campo            | Tipo | Descrizione                            |
| ---------------- | ---- | -------------------------------------- |
| `current_page`   | int  | Pagina corrente                        |
| `total_pages`    | int  | Numero totale di pagine                |
| `total_contacts` | int  | Contatti totali (filtrati da `search`) |
| `per_page`       | int  | Contatti per pagina                    |
| `showing_from`   | int  | Indice del primo contatto mostrato     |
| `showing_to`     | int  | Indice dell'ultimo contatto mostrato   |

### Oggetto limit

| Campo       | Tipo | Descrizione                                   |
| ----------- | ---- | --------------------------------------------- |
| `max`       | int  | Limite massimo di contatti per account (4000) |
| `used`      | int  | Contatti attualmente registrati               |
| `remaining` | int  | Contatti ancora inseribili                    |

## Note

* La ricerca con `search` filtra simultaneamente su numero, nome e azienda.
* Il limite massimo è di **4000 contatti per account**: vedi [Aggiungi Contatto](/mycentralino-api/contacts-create).