---
title: "List contacts with filtering and pagination"
method: GET
path: "/api/contacts.list"
---

# List contacts with filtering and pagination

`GET /api/contacts.list`

Retrieves a paginated list of contacts with optional filtering. All contact fields are always returned.

**Filtering**: Use filters to search for contacts. Text filters (email, external_id, first_name, last_name, full_name, phone, country, language) use case-insensitive partial matching (ILIKE).

**List filtering**: Use `list_id` and/or `contact_list_status` to filter contacts by list membership.

**Segment filtering**: Use `segments[]` to filter contacts that belong to specific segments.

**Contact lists**: By default, `contact_lists` is not included in the response. Set `with_contact_lists=true` to include the contact's list subscriptions.

**Pagination**: Uses cursor-based pagination. Use the `next_cursor` from the response to fetch the next page.

## Query parameters

- `workspace_id` string, required
- `email` string
- `external_id` string
- `first_name` string
- `last_name` string
- `full_name` string
- `phone` string
- `country` string
- `language` string
- `list_id` string
- `contact_list_status` 'active' | 'pending' | 'unsubscribed' | 'bounced' | 'complained'
- `segments[]` string[]
- `with_contact_lists` boolean
- `limit` integer
- `cursor` string

## Response `200`

Contacts retrieved successfully

- ListContactsResponse
  - `contacts` Contact[] — Array of contacts matching the query
    - `email` string, email, required — Email address of the contact. This is the contact's unique identifier.
    - `external_id` string, nullable — Identifier for the contact in your own system. Not unique — several contacts may share the same external_id.
    - `timezone` string, nullable — Timezone of the contact
    - `language` string, nullable — Preferred language of the contact
    - `first_name` string, nullable — First name of the contact
    - `last_name` string, nullable — Last name of the contact
    - `full_name` string, nullable — Full name of the contact (for systems that don't have separate first/last names)
    - `phone` string, nullable — Phone number of the contact
    - `address_line_1` string, nullable — First line of address
    - `address_line_2` string, nullable — Second line of address
    - `country` string, nullable — Country of the contact
    - `postcode` string, nullable — Postal code
    - `state` string, nullable — State or province
    - `job_title` string, nullable — Job title of the contact
    - `custom_string_1` string, nullable — Custom string field 1
    - `custom_string_2` string, nullable — Custom string field 2
    - `custom_string_3` string, nullable — Custom string field 3
    - `custom_string_4` string, nullable — Custom string field 4
    - `custom_string_5` string, nullable — Custom string field 5
    - `custom_number_1` number, float, nullable — Custom number field 1
    - `custom_number_2` number, float, nullable — Custom number field 2
    - `custom_number_3` number, float, nullable — Custom number field 3
    - `custom_number_4` number, float, nullable — Custom number field 4
    - `custom_number_5` number, float, nullable — Custom number field 5
    - `custom_datetime_1` string, date-time, nullable — Custom datetime field 1
    - `custom_datetime_2` string, date-time, nullable — Custom datetime field 2
    - `custom_datetime_3` string, date-time, nullable — Custom datetime field 3
    - `custom_datetime_4` string, date-time, nullable — Custom datetime field 4
    - `custom_datetime_5` string, date-time, nullable — Custom datetime field 5
    - `custom_json_1` object, nullable — Custom JSON field 1
    - `custom_json_2` object, nullable — Custom JSON field 2
    - `custom_json_3` object, nullable — Custom JSON field 3
    - `custom_json_4` object, nullable — Custom JSON field 4
    - `custom_json_5` object, nullable — Custom JSON field 5
    - `created_at` string, date-time — When the contact was created (read-only, set by server)
    - `updated_at` string, date-time — When the contact was last updated (read-only, set by server)
    - `contact_lists` ContactList[] — Lists the contact is subscribed to (read-only, included in GET responses only)
      - `email` string, email — Email address of the contact
      - `list_id` string — ID of the list
      - `list_name` string — Name of the list
      - `status` 'active' | 'pending' | 'unsubscribed' | 'bounced' | 'complained' — Subscription status
      - `created_at` string, date-time — When the contact was subscribed to this list
      - `updated_at` string, date-time — When the subscription was last updated
      - `deleted_at` string, date-time, nullable — When the subscription was deleted (null if active)
    - `contact_segments` ContactSegment[] — Segments the contact belongs to (read-only, included in GET responses only)
      - `email` string, email — Email address of the contact
      - `segment_id` string — ID of the segment
      - `version` integer — Version of the segment computation
      - `matched_at` string, date-time — When the contact was matched to this segment
      - `computed_at` string, date-time — When the segment was last computed
  - `next_cursor` string, nullable — Cursor for fetching the next page of results. Null if no more results.

## Other responses

- `400` — Bad request - invalid parameters
- `401` — Unauthorized - invalid or missing authentication token
- `500` — Internal server error

## Changes

- **2025-12-03** `04029557e460` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/pierre-b/apis/notifuse-api/changes/api/contacts.list/get.md)

---

[API](https://skmtc.dev/pierre-b/apis/notifuse-api.md) · [All operations](https://skmtc.dev/pierre-b/apis/notifuse-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pierre-b/notifuse-api/revisions/d26605f2fc47/schema)