Sign in

v1

latestOpenAPI 3.0.02026-07-2664192238.8 KB
Contacts

List 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.
get/contacts

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

OK

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"
      ],
      "updatedAt": "2021-05-20T12:30:00Z"
    }
  ],
  "paging": {
    "cursors": {
      "after": "eyJpZCI6ImNhbXAtNDU2In0",
      "before": "eyJpZCI6ImNhbXAtMTIzIn0"
    },
    "hasMore": true,
    "limit": 50
  }
}