Contacts

List contacts

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.

get/contacts

Request

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

Query parameters

limitinteger

Number of items per page. Range: 1-250. Default: 100

afterstring

Opaque cursor for fetching the next page (from paging.cursors.after)

beforestring

Opaque cursor for fetching the previous page (from paging.cursors.before)

sort'createdAt' | 'updatedAt'

Sort field. Default: createdAt

direction'asc' | 'desc'

Sort direction. Default: desc

emailstring

Filter by email address

phonestring

Filter by phone number

status'subscribed' | 'unsubscribed' | 'nonSubscribed'

Contact subscription status filter. Cannot be combined with tag

segmentIDstring

Filter by segment ID

tagstring

Filter by tag. Cannot be combined with status

updatedAtFromstring

Filter contacts updated at or after this RFC3339 timestamp. Cannot be combined with email, phone, status, segmentID, or tag

Headers

Omnisend-Versionstring required

API version that specifies the response format and behaviour

Response

Example response

{
  "contacts": [
    {
      "address": "1234 Main St",
      "birthdate": "1990-01-01",
      "city": "Los Angeles",
      "consents": [
        {
          "channel": "email",
          "createdAt": "2021-05-20T12:00:00Z",
          "ip": "161.1.1.1",
          "source": "api",
          "userAgent": "Mozilla/5.0"
        }
      ],
      "country": "United States",
      "countryCode": "US",
      "createdAt": "2021-05-20T12:00:00Z",
      "email": "example@example.com",
      "firstName": "John",
      "gender": "m",
      "id": "60a6170920d91c215e949b5c",
      "identifiers": [
        {
          "id": "example@example.com",
          "type": "email"
        }
      ],
      "lastName": "Doe",
      "optIns": [
        {
          "channel": "email",
          "optInAt": "2021-05-20T12:00:00Z"
        }
      ],
      "phone": [
        "+1234567890"
      ],
      "postalCode": "90001",
      "state": "New York",
      "status": "subscribed",
      "statuses": [
        {
          "channel": "email",
          "status": "subscribed",
          "statusChangedAt": "2021-05-20T12:00:00Z"
        }
      ],
      "tags": [
        "tag1",
        "tag2",
        "tag3"
      ],
      "trackingConsents": {
        "emailOpen": {
          "status": "given",
          "statusDate": "2026-08-01T12:00:00Z"
        }
      },
      "updatedAt": "2021-05-20T12:30:00Z"
    }
  ],
  "paging": {
    "cursors": {
      "after": "eyJpZCI6ImNhbXAtNDU2In0",
      "before": "eyJpZCI6ImNhbXAtMTIzIn0"
    },
    "hasMore": true,
    "limit": 50
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.