---
title: "List contacts"
method: GET
path: "/contacts"
tags: ["Contacts"]
---

# List contacts

`GET /contacts`

Returns a paginated list of contacts filtered by the provided query parameters.

**Scopes:**
`contacts.read`

**Filter restrictions:**
- `tag` and `status` cannot be used together in the same request.
- `updatedAtFrom` cannot be combined with `email`, `phone`, `status`, `segmentID`, or `tag`.

## Query parameters

- `limit` integer
- `after` string
- `before` string
- `sort` 'createdAt' | 'updatedAt'
- `direction` 'asc' | 'desc'
- `email` string
- `phone` string
- `status` 'subscribed' | 'unsubscribed' | 'nonSubscribed'
- `segmentID` string
- `tag` string
- `updatedAtFrom` string

## Headers

- `Omnisend-Version` string, required

## Response `200`

OK

- ListContactsResponse — Paginated list of contacts.
  - `contacts` ContactResponse[] — List of contact resources
    - `address` string — Contact Street, house number, apartment number
    - `birthdate` string — Contact birthdate in YYYY-MM-DD format
    - `city` string — Contact city
    - `consents` Consent[] — Consent records per channel, sorted by collection date (read-only)
      - `channel` 'email' | 'sms' — Channel type this consent applies to
      - `createdAt` string — Consent collection timestamp
      - `ip` string — IP address from which consent was collected
      - `source` string — Source through which consent was obtained (e.g. omnisend-form, api)
      - `userAgent` string — User agent string from the consent collection request
    - `country` string — Contact country name
    - `countryCode` string — ISO 3166-1 alpha-2 country code
    - `createdAt` string — Contact creation timestamp (read-only)
    - `customProperties` object — Custom contact properties defined for the brand
    - `email` string — Primary email address derived from the email identifier (read-only)
    - `firstName` string — Contact first name
    - `gender` 'm' | 'f' — Contact gender
    - `id` string — Contact unique identifier (read-only)
    - `identifiers` Identifier[] — Contact identifiers with channel subscription details
      - `channels` object — Subscription status per channel, keyed by channel name
      - `id` string — Identifier value (email address or phone number)
      - `type` 'email' | 'phone' — Identifier type
    - `lastName` string — Contact last name
    - `optIns` OptIn[] — Opt-in history per channel, sorted by date (read-only)
      - `channel` 'email' | 'sms' — Channel type
      - `optInAt` string — Timestamp when the opt-in was recorded
    - `phone` string[] — Phone numbers derived from phone identifiers (read-only)
    - `postalCode` string — Contact postal or ZIP code
    - `segments` string[] — IDs of segments the contact belongs to (read-only)
    - `state` string — State or province name
    - `status` 'subscribed' | 'unsubscribed' | 'nonSubscribed' — Email channel subscription status derived from the primary email identifier (read-only)
    - `statuses` ContactStatus[] — Most recent subscription status per channel, sorted by date (read-only)
      - `channel` 'email' | 'sms' — Channel type
      - `status` 'subscribed' | 'unsubscribed' | 'nonSubscribed' — Channel subscription status
      - `statusChangedAt` string — Timestamp when the status last changed
    - `tags` string[] — Labels assigned to the contact
    - `updatedAt` string — Contact last updated timestamp (read-only)
  - `paging` PagingResponse — Cursor-based pagination metadata
    - `cursors` CursorsResponse — Cursor pointers for paginating forward and backward through results
      - `after` string, nullable — Opaque cursor for fetching the next page of results
      - `before` string, nullable — Opaque cursor for fetching the previous page of results
    - `hasMore` boolean — Whether there are more items available beyond the current page
    - `limit` integer — Maximum number of items returned per page

## Other responses

- `400` — Request contains invalid or missing fields
- `401` — Authentication is missing or invalid
- `403` — Insufficient permissions for this operation
- `410` — API version has been retired
- `429` — Rate limit exceeded
- `500` — Unexpected error occurred

---

[API](https://skmtc.dev/omnisend/apis/events-api.md) · [All operations](https://skmtc.dev/omnisend/apis/events-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/omnisend/events-api/revisions/50214fbc283f/schema)