Overview
This document provides details of the List API.
Lists are called segments in Ometria.
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 Objects
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? |
|
type |
string (default: "active") |
|
in |
query |
Response
|
200 OK |
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. |
|
type |
string |
|
in |
path |
Response
|
200 OK |
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. |
|
type |
string |
|
in |
path |
|
since |
The date from which to return the list enter and list exit events |
|
type |
string (date) |
|
in |
query |
Response
|
200 OK |
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. |
|
type |
string |
|
in |
path |
|
limit |
Number of records to fetch. Max 250. |
|
integer (default: "10") |
|
|
in |
query |
|
offset |
Index of first record to fetch |
|
type |
integer |
|
in |
query |
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. |
|
type |
string |
|
in |
path |
|
limit |
Number of records to fetch. Max 5000. |
|
integer (default: "1000") |
|
|
in |
query |
|
offset |
Index of first record to fetch |
|
type |
integer |
|
in |
query |
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).
|
Value |
Type |
Description |
|
@type |
string |
The value must be "list". This shows that this record represents a list object. |
|
id |
string |
The ID of the list. |
|
title |
string |
The title of the list. |
|
description |
string |
The description of the list. |
|
status |
string, { READY , CREATING , UPDATING , ARCHIVED } |
The status of the list. |
|
type |
string, { DYNAMIC , STATIC } |
The type of the list. |
|
timestamp_created |
string (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_refreshed |
string (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_updated |
string (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. |
|
size |
integer |
The number of contacts which belong to this list. |
|
total_revenue |
number (float) |
The total revenue of contacts who belong to this list. |
|
total_orders |
integer |
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.
|
Value |
Type |
Description |
|
profile_id |
string |
The profile ID of the contact whom has entered or exited a list |
|
|
string |
The email address of the contact |
|
timestamp |
string (date-time) |
Date and time of when the change occurred. Following ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z. |
|
event |
string, { 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"
}
Comments
0 comments
Please sign in to leave a comment.