Introduction

This document provides details of the List API. It is recommended that you read both the Data API Introduction page and the Ometria Data Architecture pages before integrating with Ometria.

List Methods

List Lists

Get List

Get List Changes

Fetch List members

Export List members

List Objects

List object

List Change object


List Lists

Path

GET /lists

Description 

Fetch list of Lists (saved segments). The default behaviour is to provide active lists.

Request Parameters

mode

List "all", "archived", or "active" lists?

typestring (default: "active")
inquery

Response

200 OK
List 

List of lists as JSON array

403 Forbidden

API key is not authorised to access this resource

Response Example (200 OK)

[
  {
    "@type": "list",
    "description": "Description of the list",
    "id": "1234",
    "size": 5,
    "status": "READY",
    "timestamp_created": "2015-11-03T11:48:10+00:00",
    "timestamp_last_refreshed": "2015-11-09T14:32:02+00:00",
    "timestamp_stats_updated": "2015-11-09T14:32:03+00:00",
    "title": "Title of the list",
    "total_orders": 5,
    "total_revenue": 823.44,
    "type": "DYNAMIC"
  }
]



Get List

Path

GET /lists/{list_id}

Description

Get specific List item by ID

Request Parameters

list_id

ID of list to fetch.

typestring
inpath

Response

200 OK
List 

List object

403 Forbidden

API key is not authorised to access this resource

404 Not Found

List with specified ID was not found

Response Example (200 OK)

{
  "@type": "list",
  "description": "Description of the list",
  "id": "1234",
  "size": 5,
  "status": "READY",
  "timestamp_created": "2015-11-03T11:48:10+00:00",
  "timestamp_last_refreshed": "2015-11-09T14:32:02+00:00",
  "timestamp_stats_updated": "2015-11-09T14:32:03+00:00",
  "title": "Title of the list",
  "total_orders": 5,
  "total_revenue": 823.44,
  "type": "DYNAMIC"
}



Get List Changes

Path

GET /lists/{list_id}/changes

Description

Return the list_enter and list_exit events for a specific list since a specified date. Note, dynamic lists are updated every 4-6 hours. If you require the latest data to be returned, refresh the list in the Ometria platform.

Request Parameters

list_id

ID of list to fetch.

typestring
inpath
since

The date from which to return the list enter and list exit events

typestring (date)
inquery

Response

200 OK
ListChanges 

List object

403 Forbidden

API key is not authorised to access this resource

404 Not Found

List with specified ID was not found

Response Example (200 OK)

{
  "email": "john.smith@example.com",
  "event": "list_enter",
  "profile_id": "27f4-9cb0b1-40719",
  "timestamp": "2017-02-02 10:18:12.833949+00"
}



Fetch List members

Path

GET /lists/{list_id}/contacts

Description

Return contacts in the list as a JSON array

Request Parameters

list_id

ID of list to fetch.

typestring
inpath
limit

Number of records to fetch. Max 250.


integer (default: "10")
inquery
offset

Index of first record to fetch

typeinteger
inquery

Response

200 OK
Array<Contact

List of contact objects

403 Forbidden

API key is not authorised to access this resource

404 Not Found

List with specified ID was not found

Response Example (200 OK)

[
  {
    "@add_to_lists": [
      1,
      2,
      3
    ],
    "@collection": "default",
    "@remove_from_lists": [
      4,
      5,
      6
    ],
    "@type": "contact",
    "country_id": "GB",
    "customer_id": "7898734",
    "date_of_birth": "1985-01-05",
    "email": "john.smith@example.com",
    "firstname": "John",
    "gender": "m",
    "id": "123",
    "lastname": "Smith",
    "marketing_optin": "EXPLICITLY_OPTEDIN",
    "middlename": "Fredrick",
    "phone_number": "+447812123456",
    "prefix": "Mr",
    "properties": {
      "nickname": "Johnny",
      "number_of_cats": 4
    },
    "store_ids": [
      "gb"
    ],
    "timestamp_subscribed": "2015-01-02T09:00:00+00"
  }
]



Export List members

Path

GET /lists/{list_id}/contacts_export

Description

Return contacts in the list as line delimited (separated by "\n") JSON objects, suitable for streaming

Request Parameters

list_id

ID of list to fetch.

typestring
inpath
limit

Number of records to fetch. Max 5000.


integer (default: "1000")
inquery
offset

Index of first record to fetch

typeinteger
inquery

Response

200 OK
Array<Contact

Return contacts as line delimited (separated by "\n") JSON objects, suitable for streaming

403 Forbidden

API key is not authorised to access this resource

404 Not Found

List with specified ID was not found

Response Example (200 OK)

{
  "@add_to_lists": [
    1,
    2,
    3
  ],
  "@collection": "default",
  "@remove_from_lists": [
    4,
    5,
    6
  ],
  "@type": "contact",
  "country_id": "GB",
  "customer_id": "7898734",
  "date_of_birth": "1985-01-05",
  "email": "john.smith@example.com",
  "firstname": "John",
  "gender": "m",
  "id": "123",
  "lastname": "Smith",
  "marketing_optin": "EXPLICITLY_OPTEDIN",
  "middlename": "Fredrick",
  "phone_number": "+447812123456",
  "prefix": "Mr",
  "properties": {
    "nickname": "Johnny",
    "number_of_cats": 4
  },
  "store_ids": [
    "gb"
  ],
  "timestamp_subscribed": "2015-01-02T09:00:00+00"
}



List: object


Describes a segment in Ometria (a dynamic or static list of Contacts).

ValueTypeDescription
@typestring

The value must be "list". This shows that this record represents a list object.


idstring

The ID of the list.


titlestring

The title of the list.


descriptionstring

The description of the list.


statusstring, { READY , CREATING , UPDATING , ARCHIVED }

The status of the list.


typestring, { DYNAMIC , STATIC }

The type of the list.


timestamp_createdstring (date-time)

Date and time of when the list was created. Following ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z.


timestamp_last_refreshedstring (date-time)

Date and time of when the list was last refreshed. Following ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z.


timestamp_stats_updatedstring (date-time)
Date and time of when the list's stats (size, total_revenue and total_orders) were last updated. Following ISO 8601 dateTime format with timezone offsetYYYY-MM-DDThh:mm:ss+Z.
sizeinteger

The number of contacts which belong to this list.


total_revenuenumber (float)
The total revenue of contacts who belong to this list.
total_ordersinteger

The total number of orders which have been placed by contacts who belong to this list.


Example

{
  "@type": "list",
  "description": "Description of the list",
  "id": "1234",
  "size": 5,
  "status": "READY",
  "timestamp_created": "2015-11-03T11:48:10+00:00",
  "timestamp_last_refreshed": "2015-11-09T14:32:02+00:00",
  "timestamp_stats_updated": "2015-11-09T14:32:03+00:00",
  "title": "Title of the list",
  "total_orders": 5,
  "total_revenue": 823.44,
  "type": "DYNAMIC"
}



ListChanges: object

Describes a change to a segment (list), the data returned is the records that have entered or left a list, not a full list of entries in that list.

ValueTypeDescription
profile_idstring

The profile ID of the contact whom has entered or exited a list


emailstring

The email address of the contact


timestampstring (date-time)

Date and time of when the change occurred. Following ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z.


eventstring, { list_enter , list_exit }

The type of list change event

Example

{
  "email": "john.smith@example.com",
  "event": "list_enter",
  "profile_id": "27f4-9cb0b1-40719",
  "timestamp": "2017-02-02 10:18:12.833949+00"
}