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

# List contacts

`GET /contacts`

## Request

- Base URL: `https://api.omnisend.com/api`
- URL: `https://api.omnisend.com/api/contacts`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `https://app.omnisend.com/oauth2/token` scopes: `contacts.read`
  - API key in header `Authorization`

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

**Scopes:**
`contacts.read`

**Rate Limiting:**
This endpoint is rate limited to 400 requests per minute.

**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
    - `trackingConsents` ContactTrackingConsents: Contact-level tracking consents.
      - `emailOpen` EmailOpenTrackingConsent: Email open tracking consent record.
        - `status` 'given' | 'declined': Consent status
        - `statusDate` string: Timestamp when the consent status was collected
    - `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/contacts-api.md) - [All operations](https://skmtc.dev/omnisend/apis/contacts-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnisend/apis/contacts-api/revisions/e5a9a2dd0050?raw)