# List contacts

> Page through your contacts, with search and filters for subscription status, list, and segment.

`GET https://api-connect.nxiom.com/api/v1/emails/contacts`

## Authorization

Requires `email.full_access`.

## Query parameters

| Field | Type | Description |
| --- | --- | --- |
| `page` | integer · optional | Page number, starting at `1`. Default `1`. |
| `limit` | integer · optional | 1–100. Default `50`. |
| `search` | string · optional | Match contacts by email or name. |
| `emailStatus` | string · optional | `subscribed` or `unsubscribed`. |
| `listId` | string · optional | Only contacts in this list. |
| `segmentId` | string · optional | Only contacts in this segment. |

## Request

### cURL

```shell
curl "https://api-connect.nxiom.com/api/v1/emails/contacts?page=1&limit=50&emailStatus=subscribed" \
  -H "Authorization: Bearer $NEXIOM_API_KEY"
```

### Node.js

```typescript
import { NexiomConnect } from '@nexiom/connect';

const apiKey = process.env.NEXIOM_API_KEY;
if (!apiKey) throw new Error('Set NEXIOM_API_KEY');

const nexiom = new NexiomConnect({ apiKey });

const { data, error } = await nexiom.contacts.list({ page: 1, limit: 50, emailStatus: 'subscribed' });

if (error) throw new Error(`${error.code}: ${error.message}`);
for (const contact of data.items) {
  console.log(contact.id, contact.email);
}

console.log(`${data.items.length} of ${data.total}`);
```

### PHP

```php
<?php

use Nexiom\Connect\NexiomConnect;

$apiKey = getenv('NEXIOM_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set NEXIOM_API_KEY');
}

$nexiom = new NexiomConnect($apiKey);

$page = $nexiom->contacts->list([
    'page' => 1,
    'limit' => 50,
    'emailStatus' => 'subscribed',
]);

foreach ($page['items'] as $contact) {
    echo $contact['id'], ' ', $contact['email'], PHP_EOL;
}
```

## Response

HTTP `200`. Results are under `data`, with page-based [pagination](/docs/api/pagination).

| Field | Type | Description |
| --- | --- | --- |
| `items` | array | Contacts on this page, each with `id`, `email`, names, `phone_number`, `email_status`, and `created_at`. |
| `total` | number | Contacts matching the filters. |
| `page` | number | The page returned. |
| `limit` | number | The page size. |

### 200 OK

Example response. Identifiers are illustrative.

```json
{
  "message": "Contacts fetched",
  "data": {
    "items": [
      {
        "id": "con_example",
        "email": "reader@example.com",
        "phone_number": null,
        "first_name": "Sam",
        "last_name": "Rivera",
        "email_status": "subscribed",
        "created_at": "2026-10-02T10:00:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50
  }
}
```

### 400 Bad Request

The request is invalid. Correct it before retrying; `details` lists the failing fields.

```json
{
  "error": "invalid_argument",
  "message": "Request doesn't match the schema",
  "correlationId": "req_example",
  "details": {
    "context": "body",
    "issues": []
  }
}
```

### 401 Unauthorized

The API key is missing, malformed, revoked, or expired.

```json
{
  "error": "unauthorized",
  "message": "Invalid API key",
  "correlationId": "req_example"
}
```

### 403 Forbidden

The API key lacks a required permission, or its domain restriction does not allow this sender.

```json
{
  "error": "not_allowed",
  "message": "Missing required API key permissions: email.full_access",
  "correlationId": "req_example"
}
```

---

Source: https://connect.nxiom.com/docs/api/contacts/list