Ometria data API API Reference

Welcome to the Ometria API reference.

The Ometria API is organized around the REST methodology, and it uses resource-oriented URLs, and common HTTP response codes to indicate API errors. All requests are authenticated using an API key which can be obtained from your account settings.

HTTPS

All requests to the Ometria API MUST be carried out via HTTPS. API servers do not listen on unsecured HTTP ports to avoid the possibility of insecure information exchange.

Message encoding

The V2 Ometria API uses JSON encoding for all data exchanges and assumes UTF-8 character encoding throughout.

Rate limits

The Ometria API has a default rate limit of 4 requests per second per Ometria account. If you expect to exceed this limit, please contact us.

In the case of your application being rate limited, the HTTP code 429 (too many requests) will be returned. In this case your application should reduce the number of requests it is trying to send.

Note that the asynchronous push API also has a maximum of 50,000 asynchronous import records. If you attempt to push more than this number of records in a short timeframe, you will also receive the HTTP 429 status code.

API Endpoint
https://api.ometria.com/v2
Contact: support@ometria.com
Schemes: https
Version: 2.1.0

Authentication

apikey

name
X-Ometria-Auth
in
header
description
Ometria API key which can be obtained from your Ometria account administrator

Products

List Products

GET /products

Return a list of products with optional filters

limit

Number of items to return. Max 250.

type
string 10
in
query
offset

Index of first record.

type
string 0
in
query
active

Should we return only active or inactive products? true for return only active. false for return only inactive. If not defined, active and inactive products are returned.

type
string , x ∈ { true , false }
in
query
200 OK

List of Product objects

403 Forbidden

API key is not authorised to access this resource

Response Example (200 OK)
[
  {
    "@type": "product",
    "attributes": [
      {
        "id": "category:womens",
        "label": "Womens",
        "type": "category"
      },
      {
        "id": "style:casual",
        "label": "Casual",
        "type": "style"
      }
    ],
    "id": "12345",
    "image_url": "http://www.example.com/product.jpg",
    "is_active": true,
    "listings": [
      {
        "currency": "EUR",
        "image_url": "http://www.example.com/fr/product.jpg",
        "is_active": true,
        "price": 50,
        "store": "example.com/fr",
        "title": "Produit d'essai",
        "url": "http://www.example.com/fr/product.html"
      },
      {
        "currency": "EUR",
        "image_url": "http://www.example.com/de/product.jpg",
        "is_active": false,
        "price": 50,
        "store": "example.com/de",
        "title": "Das Product",
        "url": "http://www.example.com/de/product.html"
      }
    ],
    "price": 50,
    "properties": {
      "custom_key": "custom value"
    },
    "sku": "FHSG-2738-FHI",
    "special_price": 45,
    "special_price_dt_from": "2015-03-02T09:00:00+00",
    "special_price_dt_to": "2015-01-02T09:00:00+00",
    "title": "Test Product",
    "url": "http://www.example.com/product.html"
  }
]

Get Product

GET /products/{product_id}

Return a single Product item

product_id

ID of product to fetch.

type
string
in
path
200 OK

Product object

403 Forbidden

API key is not authorised to access this resource

404 Not Found

Product with specified ID was not found

Response Example (200 OK)
{
  "@type": "product",
  "attributes": [
    {
      "id": "category:womens",
      "label": "Womens",
      "type": "category"
    },
    {
      "id": "style:casual",
      "label": "Casual",
      "type": "style"
    }
  ],
  "id": "12345",
  "image_url": "http://www.example.com/product.jpg",
  "is_active": true,
  "listings": [
    {
      "currency": "EUR",
      "image_url": "http://www.example.com/fr/product.jpg",
      "is_active": true,
      "price": 50,
      "store": "example.com/fr",
      "title": "Produit d'essai",
      "url": "http://www.example.com/fr/product.html"
    },
    {
      "currency": "EUR",
      "image_url": "http://www.example.com/de/product.jpg",
      "is_active": false,
      "price": 50,
      "store": "example.com/de",
      "title": "Das Product",
      "url": "http://www.example.com/de/product.html"
    }
  ],
  "price": 50,
  "properties": {
    "custom_key": "custom value"
  },
  "sku": "FHSG-2738-FHI",
  "special_price": 45,
  "special_price_dt_from": "2015-03-02T09:00:00+00",
  "special_price_dt_to": "2015-01-02T09:00:00+00",
  "title": "Test Product",
  "url": "http://www.example.com/product.html"
}

Create Product

POST /products/{product_id}

Create a new product or update an existing product

Product object

product_id

ID of product being created or updated.

type
string
in
path
Request Example
{
  "@type": "product",
  "attributes": [
    {
      "id": "category:womens",
      "label": "Womens",
      "type": "category"
    },
    {
      "id": "style:casual",
      "label": "Casual",
      "type": "style"
    }
  ],
  "id": "12345",
  "image_url": "http://www.example.com/product.jpg",
  "is_active": true,
  "listings": [
    {
      "currency": "EUR",
      "image_url": "http://www.example.com/fr/product.jpg",
      "is_active": true,
      "price": 50,
      "store": "example.com/fr",
      "title": "Produit d'essai",
      "url": "http://www.example.com/fr/product.html"
    },
    {
      "currency": "EUR",
      "image_url": "http://www.example.com/de/product.jpg",
      "is_active": false,
      "price": 50,
      "store": "example.com/de",
      "title": "Das Product",
      "url": "http://www.example.com/de/product.html"
    }
  ],
  "price": 50,
  "properties": {
    "custom_key": "custom value"
  },
  "sku": "FHSG-2738-FHI",
  "special_price": 45,
  "special_price_dt_from": "2015-03-02T09:00:00+00",
  "special_price_dt_to": "2015-01-02T09:00:00+00",
  "title": "Test Product",
  "url": "http://www.example.com/product.html"
}
200 OK

Product object successfully created or updated

403 Forbidden

API key is not authorised to access this resource

Orders

List Orders

GET /orders

List orders with optional filters

limit

Number of items to return. Max 250.

type
string 10
in
query
offset

Index of first record.

type
string 0
in
query
200 OK

List of Order objects

403 Forbidden

API key is not authorised to access this resource

Response Example (200 OK)
[
  {
    "@type": "order",
    "billing_address": {
      "city": "London",
      "country_code": "GB",
      "postcode": "W1K 4TG",
      "state": "Greater London"
    },
    "channel": "online",
    "coupon_code": "FJ45-TJ5Y-5YK3-T894",
    "currency": "GBP",
    "customer": {
      "email": "john.smith@example.com",
      "firstname": "John",
      "lastname": "Smith"
    },
    "discount": -5,
    "grand_total": 96.4,
    "id": "123553",
    "ip_address": "127.0.0.1",
    "is_valid": true,
    "lineitems": [
      {
        "product_id": "SS14-059493",
        "properties": {
          "custom_key": "custom value"
        },
        "quantity": 2,
        "sku": "SS14-059493-S5",
        "total": 100,
        "unit_price": 50,
        "variant_options": [
          {
            "id": "large",
            "label": "Large",
            "type": "size"
          },
          {
            "id": "color-45",
            "label": "Blue",
            "type": "color"
          }
        ]
      }
    ],
    "payment_method": "card",
    "properties": {
      "custom_key": "custom value"
    },
    "shipping": 2,
    "shipping_address": {
      "city": "London",
      "country_code": "GB",
      "postcode": "W1K 4TG",
      "state": "Greater London"
    },
    "shipping_method": "standard",
    "status": "complete",
    "store": "example.com/en",
    "subtotal": 83.33,
    "tax": 16.07,
    "timestamp": "2015-01-02T09:00:00+00",
    "web_id": "891743"
  }
]

Get Order

GET /orders/{order_id}

Return a single Order item

order_id

ID of order to fetch.

type
string
in
path
limit

Number of items to return. Max 250.

type
string 10
in
query
offset

Index of first record.

type
string 0
in
query
200 OK

Order object

403 Forbidden

API key is not authorised to access this resource

404 Not Found

Order with specified ID was not found

Response Example (200 OK)
{
  "@type": "order",
  "billing_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "channel": "online",
  "coupon_code": "FJ45-TJ5Y-5YK3-T894",
  "currency": "GBP",
  "customer": {
    "email": "john.smith@example.com",
    "firstname": "John",
    "lastname": "Smith"
  },
  "discount": -5,
  "grand_total": 96.4,
  "id": "123553",
  "ip_address": "127.0.0.1",
  "is_valid": true,
  "lineitems": [
    {
      "product_id": "SS14-059493",
      "properties": {
        "custom_key": "custom value"
      },
      "quantity": 2,
      "sku": "SS14-059493-S5",
      "total": 100,
      "unit_price": 50,
      "variant_options": [
        {
          "id": "large",
          "label": "Large",
          "type": "size"
        },
        {
          "id": "color-45",
          "label": "Blue",
          "type": "color"
        }
      ]
    }
  ],
  "payment_method": "card",
  "properties": {
    "custom_key": "custom value"
  },
  "shipping": 2,
  "shipping_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "shipping_method": "standard",
  "status": "complete",
  "store": "example.com/en",
  "subtotal": 83.33,
  "tax": 16.07,
  "timestamp": "2015-01-02T09:00:00+00",
  "web_id": "891743"
}

Create Order

POST /orders/{order_id}

Create new or update an existing order

Order object. For multicurrency use OrderExtended.

order_id

ID of order being created or updated.

type
string
in
path
Request Example
{
  "@type": "order",
  "billing_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "channel": "online",
  "coupon_code": "FJ45-TJ5Y-5YK3-T894",
  "currency": "GBP",
  "customer": {
    "email": "john.smith@example.com",
    "firstname": "John",
    "lastname": "Smith"
  },
  "discount": -5,
  "grand_total": 96.4,
  "id": "123553",
  "ip_address": "127.0.0.1",
  "is_valid": true,
  "lineitems": [
    {
      "product_id": "SS14-059493",
      "properties": {
        "custom_key": "custom value"
      },
      "quantity": 2,
      "sku": "SS14-059493-S5",
      "total": 100,
      "unit_price": 50,
      "variant_options": [
        {
          "id": "large",
          "label": "Large",
          "type": "size"
        },
        {
          "id": "color-45",
          "label": "Blue",
          "type": "color"
        }
      ]
    }
  ],
  "payment_method": "card",
  "properties": {
    "custom_key": "custom value"
  },
  "shipping": 2,
  "shipping_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "shipping_method": "standard",
  "status": "complete",
  "store": "example.com/en",
  "subtotal": 83.33,
  "tax": 16.07,
  "timestamp": "2015-01-02T09:00:00+00",
  "web_id": "891743"
}
200 OK

Order object successfully created or updated

403 Forbidden

API key is not authorised to access this resource

GDPR anonymization requests

List GDPR related data anonymization requests

GET /data-deletion-requests

Returns previously filed GDPR related data anonymization requests and their status.

An array of data anonymization objects.

403 Forbidden

API key is not authorised to access this resource.

Response Example (200 OK)
[
  {
    "action": "anonymise",
    "comment": "Some comment",
    "id": "a8c53a39-e0fc-462c-b5fa-907fe70a4174",
    "identities": [
      {
        "hashed_email": "3af31748a10ef8bd28ce7620c25fe18d@anonymous.ometria"
      }
    ],
    "source": {
      "api_request_id": "a8c53a39-e0fc-462c-b5fa-907fe70a4174",
      "origin": "api",
      "user": {
        "email": "user@user.com",
        "name": "A user"
      }
    },
    "summary": "1 contact record anonymised, 15 events anonymise",
    "timestamp_completed": "2017-02-04 10:18:12.833949+00",
    "timestamp_created": "2017-02-02 10:18:12.833949+00"
  }
]

Create new GDPR data anonymization request

POST /data-deletion-requests

Create new or update an existing order

The email address of the individual who had requested anonymization

Request Example
{
  "action": "anonymise",
  "comment": "Some comment",
  "email_address": "someone@domain.com"
}

GDPR data anonymization request object successfully created

403 Forbidden

API key is not authorised to access this resource

Response Example (200 OK)
{
  "action": "anonymise",
  "comment": "Some comment",
  "id": "a8c53a39-e0fc-462c-b5fa-907fe70a4174",
  "identities": [
    {
      "hashed_email": "3af31748a10ef8bd28ce7620c25fe18d@anonymous.ometria"
    }
  ],
  "source": {
    "api_request_id": "a8c53a39-e0fc-462c-b5fa-907fe70a4174",
    "origin": "api",
    "user": {
      "email": "user@user.com",
      "name": "A user"
    }
  },
  "summary": "1 contact record anonymised, 15 events anonymise",
  "timestamp_completed": "2017-02-04 10:18:12.833949+00",
  "timestamp_created": "2017-02-02 10:18:12.833949+00"
}

Get details of specific GDPR related data anonymization request

GET /data-deletion-requests/{id}

Returns details and status of GDPR related data anonymization request by its ID.

id

The request ID

type
string
in
query

A data anonymization object.

403 Forbidden

API key is not authorised to access this resource.

404 Not Found

Data anonymization request with specified ID was not found

Response Example (200 OK)
{
  "action": "anonymise",
  "comment": "Some comment",
  "id": "a8c53a39-e0fc-462c-b5fa-907fe70a4174",
  "identities": [
    {
      "hashed_email": "3af31748a10ef8bd28ce7620c25fe18d@anonymous.ometria"
    }
  ],
  "source": {
    "api_request_id": "a8c53a39-e0fc-462c-b5fa-907fe70a4174",
    "origin": "api",
    "user": {
      "email": "user@user.com",
      "name": "A user"
    }
  },
  "summary": "1 contact record anonymised, 15 events anonymise",
  "timestamp_completed": "2017-02-04 10:18:12.833949+00",
  "timestamp_created": "2017-02-02 10:18:12.833949+00"
}

Contacts

List Collections

GET /contacts

List contact collections along with counts of records in each collection

limit

Number of items to return. Max 250.

type
string 10
in
query
offset

Index of first record.

type
string 0
in
query

Collection objects

403 Forbidden

API key is not authorised to access this resource

Response Example (200 OK)
[
  {
    "collection": "default",
    "count": 43540
  }
]

List Contacts

GET /contacts/{collection}

List Contacts in Collection with optional filters

collection

ID of collection to fetch.

type
string
in
path
limit

Number of items to return. Max 250.

type
string 10
in
query
offset

Index of first record.

type
string 0
in
query
200 OK

List of Contact objects

403 Forbidden

API key is not authorised to access this resource

Response Example (200 OK)
[
  {
    "@add_to_lists": [
      1,
      2,
      3
    ],
    "@collection": "default",
    "@remove_from_lists": [
      4,
      5,
      6
    ],
    "@type": "contact",
    "channels": {
      "sms": {
        "allow_marketing": true,
        "allow_transactional": true,
        "dt_updated_marketing": "2015-01-02T09:00:00+00",
        "dt_updated_transactional": "2015-01-02T09:00:00+00"
      }
    },
    "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"
  }
]

Get Contact listing

GET /contacts/{collection}/{contact_id}

Return a single Contact record

collection

ID of collection to which the contact belongs.

type
string
in
path
contact_id

ID of contact to fetch.

type
string
in
path
200 OK

Returns a contact record

403 Forbidden

API key is not authorised to access this resource

404 Not Found

Record with this ID does not exist

Response Example (200 OK)
{
  "@add_to_lists": [
    1,
    2,
    3
  ],
  "@collection": "default",
  "@remove_from_lists": [
    4,
    5,
    6
  ],
  "@type": "contact",
  "channels": {
    "sms": {
      "allow_marketing": true,
      "allow_transactional": true,
      "dt_updated_marketing": "2015-01-02T09:00:00+00",
      "dt_updated_transactional": "2015-01-02T09:00:00+00"
    }
  },
  "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"
}

Create Contact listing

POST /contacts/{collection}/{contact_id}

Create a new contact or update an existing contact (there is no need to create a collection before adding records)

Contact object

collection

ID of collection to create or update.

type
string
in
path
contact_id

ID of contact to create or update.

type
string
in
path
Request Example
{
  "@add_to_lists": [
    1,
    2,
    3
  ],
  "@collection": "default",
  "@remove_from_lists": [
    4,
    5,
    6
  ],
  "@type": "contact",
  "channels": {
    "sms": {
      "allow_marketing": true,
      "allow_transactional": true,
      "dt_updated_marketing": "2015-01-02T09:00:00+00",
      "dt_updated_transactional": "2015-01-02T09:00:00+00"
    }
  },
  "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"
}
200 OK

Contact object successfully created or updated

403 Forbidden

API key is not authorised to access this resource

Custom Event

Returns a list of custom events

GET /custom-events/

Returns a list of custom events

limit

Number of items to return. Max 250.

type
string 10
in
query
offset

Index of first record.

type
string 0
in
query
200 OK

List of custom event objects

403 Forbidden

API key is not authorised to access this resource

Response Example (200 OK)
[
  {
    "@type": "custom_event",
    "event_type": "whatever",
    "id": "xxxxxx",
    "identity_account_id": "",
    "identity_email": "",
    "profile_id": "xxxxx",
    "properties": {
    },
    "timestamp": "2017-05-01T14:00:00Z"
  }
]

Triggers a custom event

POST /custom-events/

Triggers a custom event in the Ometria platform.

Custom Event object

Request Example
{
  "@type": "custom_event",
  "event_type": "whatever",
  "id": "xxxxxx",
  "identity_account_id": "",
  "identity_email": "",
  "profile_id": "xxxxx",
  "properties": {
  },
  "timestamp": "2017-05-01T14:00:00Z"
}
200 OK

Custom Event successfully received

403 Forbidden

API key is not authorised to access this resource

Returns a list of custom events of a specific type

GET /custom-events/{event_type}

Returns a list of custom events of a specific type

event_type

The event type

type
string
in
path
limit

Number of items to return. Max 250.

type
string 10
in
query
offset

Index of first record.

type
string 0
in
query
200 OK

List of custom event objects

403 Forbidden

API key is not authorised to access this resource

Response Example (200 OK)
[
  {
    "@type": "custom_event",
    "event_type": "whatever",
    "id": "xxxxxx",
    "identity_account_id": "",
    "identity_email": "",
    "profile_id": "xxxxx",
    "properties": {
    },
    "timestamp": "2017-05-01T14:00:00Z"
  }
]

Returns a specific custom event

GET /custom-events/{event_type}/{event_id}

Returns a specific custom event

event_type

The event type

type
string
in
path
event_id

The event ID

type
string
in
path
200 OK

A single custom event object

403 Forbidden

API key is not authorised to access this resource

404 Not Found

The specific custom event could not be found

Response Example (200 OK)
{
  "@type": "custom_event",
  "event_type": "whatever",
  "id": "xxxxxx",
  "identity_account_id": "",
  "identity_email": "",
  "profile_id": "xxxxx",
  "properties": {
  },
  "timestamp": "2017-05-01T14:00:00Z"
}

Profiles

Fetch list of profiles

GET /profiles/

Return profiles as a JSON array

limit

Number of records to fetch. Max 250.

type
integer 10
in
query
offset

Index of first record to fetch

type
integer
in
query
updateSince

Only return profiles which have been updated since this date

type
string (date)
in
query
200 OK

List of profile 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)
[
  {
    "@type": "profile",
    "country": null,
    "customer_id": "55555",
    "date_of_birth": "1984-04-22",
    "dates": {
      "acquired": "2014-11-01T15:34:35+00:00",
      "first_purchase": "2015-02-01T05:44:55+00:00",
      "first_seen": "2014-12-01T05:44:55+00:00",
      "last_purchase": "2015-02-01T05:44:55+00:00",
      "last_seen": "2015-02-01T05:44:55+00:00"
    },
    "email": "bob22@example.com",
    "firstname": null,
    "gender": "m",
    "id": "2695-c473e2-4aaf58",
    "identities": [
      {
        "id": "bob22@example.com",
        "type": "email"
      }
    ],
    "lastname": "smith111",
    "marketing_optin": null,
    "middlename": null,
    "name": "smith111",
    "prefix": null,
    "properties": {
      "custom_key": "custom value"
    },
    "seen": false,
    "stats": {
      "aov": 99.17,
      "orders": 1,
      "orders_attempted": 1,
      "revenue": 99.17,
      "total_items": 5,
      "visits": 20
    },
    "suffix": null,
    "tags": [
      "Attended VIP event 2017"
    ]
  }
]

Fetch individual profile

GET /profiles/{profile_id}

Return profile as a JSON object

profile_id

ID of the profile to fetch.

type
string
in
path
200 OK

Return a single profile record

403 Forbidden

API key is not authorised to access this resource

404 Not Found

Profile with specified ID was not found

Response Example (200 OK)
{
  "@type": "profile",
  "country": null,
  "customer_id": "55555",
  "date_of_birth": "1984-04-22",
  "dates": {
    "acquired": "2014-11-01T15:34:35+00:00",
    "first_purchase": "2015-02-01T05:44:55+00:00",
    "first_seen": "2014-12-01T05:44:55+00:00",
    "last_purchase": "2015-02-01T05:44:55+00:00",
    "last_seen": "2015-02-01T05:44:55+00:00"
  },
  "email": "bob22@example.com",
  "firstname": null,
  "gender": "m",
  "id": "2695-c473e2-4aaf58",
  "identities": [
    {
      "id": "bob22@example.com",
      "type": "email"
    }
  ],
  "lastname": "smith111",
  "marketing_optin": null,
  "middlename": null,
  "name": "smith111",
  "prefix": null,
  "properties": {
    "custom_key": "custom value"
  },
  "seen": false,
  "stats": {
    "aov": 99.17,
    "orders": 1,
    "orders_attempted": 1,
    "revenue": 99.17,
    "total_items": 5,
    "visits": 20
  },
  "suffix": null,
  "tags": [
    "Attended VIP event 2017"
  ]
}

Lists

List Lists

GET /lists

Fetch list of Lists (saved segments)

mode

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

type
string active
in
query
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

GET /lists/{list_id}

Get specific List item by ID

list_id

ID of list to fetch.

type
string
in
path
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

GET /lists/{list_id}/changes

Return the list_enter and list_exit events for a specific list since a specified date

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
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

GET /lists/{list_id}/contacts

Return contacts in the list as a JSON array

list_id

ID of list to fetch.

type
string
in
path
limit

Number of records to fetch. Max 250.

type
integer 10
in
query
offset

Index of first record to fetch

type
integer
in
query
200 OK

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",
    "channels": {
      "sms": {
        "allow_marketing": true,
        "allow_transactional": true,
        "dt_updated_marketing": "2015-01-02T09:00:00+00",
        "dt_updated_transactional": "2015-01-02T09:00:00+00"
      }
    },
    "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

GET /lists/{list_id}/contacts_export

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

list_id

ID of list to fetch.

type
string
in
path
limit

Number of records to fetch. Max 5000

type
integer 1000
in
query
offset

Index of first record to fetch

type
integer
in
query
200 OK

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",
  "channels": {
    "sms": {
      "allow_marketing": true,
      "allow_transactional": true,
      "dt_updated_marketing": "2015-01-02T09:00:00+00",
      "dt_updated_transactional": "2015-01-02T09:00:00+00"
    }
  },
  "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"
}

Transactional Email

Send Transactional Email

POST /transactional-email/send

Send a transactional email

Transactional Email object

Request Example
{
  "data": {
  },
  "from": {
    "email": "j.smith@example.com",
    "name": "John Smith"
  },
  "profile_id": "",
  "reply_to": {
    "email": "j.smith@example.com",
    "name": "John Smith"
  },
  "sandbox": true,
  "stream": "87tgHafe",
  "subject": "Email Subject",
  "template_id": 3,
  "to": {
    "email": "j.smith@example.com",
    "name": "John Smith"
  },
  "transactional": true
}
200 OK

Email successfully sent

403 Forbidden

API key is not authorised to access this resource

Push

Push objects

POST /push

Accepts a list of up to 100 order/contact/product/custom event records as a list.

Push object

Request Example
[
  {
    "@type": "order",
    "billing_address": {
      "city": "London",
      "country_code": "GB",
      "postcode": "W1K 4TG",
      "state": "Greater London"
    },
    "channel": "online",
    "coupon_code": "FJ45-TJ5Y-5YK3-T894",
    "currency": "GBP",
    "customer": {
      "email": "john.smith@example.com",
      "firstname": "John",
      "lastname": "Smith"
    },
    "discount": -5,
    "grand_total": 96.4,
    "id": "123553",
    "ip_address": "127.0.0.1",
    "is_valid": true,
    "lineitems": [
      {
        "product_id": "SS14-059493",
        "properties": {
          "custom_key": "custom value"
        },
        "quantity": 2,
        "sku": "SS14-059493-S5",
        "total": 100,
        "unit_price": 50,
        "variant_options": [
          {
            "id": "large",
            "label": "Large",
            "type": "size"
          },
          {
            "id": "color-45",
            "label": "Blue",
            "type": "color"
          }
        ]
      }
    ],
    "payment_method": "card",
    "properties": {
      "custom_key": "custom value"
    },
    "shipping": 2,
    "shipping_address": {
      "city": "London",
      "country_code": "GB",
      "postcode": "W1K 4TG",
      "state": "Greater London"
    },
    "shipping_method": "standard",
    "status": "complete",
    "store": "example.com/en",
    "subtotal": 83.33,
    "tax": 16.07,
    "timestamp": "2015-01-02T09:00:00+00",
    "web_id": "891743"
  }
]
202 Accepted

Push object accepted

403 Forbidden

API key is not authorised to access this resource

Response Example (202 Accepted)
{
  "accepted": 1,
  "rejected": 0,
  "request_id": "c2da7180-52b2-11e7-92d6-0a3dc0ca7bee",
  "skipped": 0,
  "status": "OK"
}

List errors

GET /push/_errors

Return a list of the 100 latest push record errors

200 OK

List of Errors object

403 Forbidden

API key is not authorised to access this resource

Response Example (200 OK)
[
  {
    "message": {
      "error_message": "not a valid value",
      "error_path": "root > gender"
    },
    "record": {
      "@source": "api",
      "@type": "contact",
      "account": 239,
      "country_id": "GB",
      "customer_id": "7898734",
      "date_of_birth": "1985-01-05",
      "email": "john.smith@example.com",
      "firstname": "John",
      "gender": 12,
      "id": "123456",
      "lastname": "Smith",
      "marketing_optin": "EXPLICITLY_OPTEDIN",
      "middlename": "Fredrick",
      "prefix": "Mr",
      "properties": {
        "nickname": "Johnny",
        "number_of_cats": 4
      },
      "timestamp_acquired": "2015-01-02"
    },
    "record_id": "123456",
    "record_type": "contact",
    "request_id": "ed926048-52af-11e7-aa8c-0a3dc0ca7bee",
    "timestamp": "2017-06-16 16:22:06.705677+00"
  }
]

Errors

List errors

GET /push/_errors

Return a list of the 100 latest push record errors

200 OK

List of Errors object

403 Forbidden

API key is not authorised to access this resource

Response Example (200 OK)
[
  {
    "message": {
      "error_message": "not a valid value",
      "error_path": "root > gender"
    },
    "record": {
      "@source": "api",
      "@type": "contact",
      "account": 239,
      "country_id": "GB",
      "customer_id": "7898734",
      "date_of_birth": "1985-01-05",
      "email": "john.smith@example.com",
      "firstname": "John",
      "gender": 12,
      "id": "123456",
      "lastname": "Smith",
      "marketing_optin": "EXPLICITLY_OPTEDIN",
      "middlename": "Fredrick",
      "prefix": "Mr",
      "properties": {
        "nickname": "Johnny",
        "number_of_cats": 4
      },
      "timestamp_acquired": "2015-01-02"
    },
    "record_id": "123456",
    "record_type": "contact",
    "request_id": "ed926048-52af-11e7-aa8c-0a3dc0ca7bee",
    "timestamp": "2017-06-16 16:22:06.705677+00"
  }
]

Unsubscribes

Receive unsubscribed contacts within a time range.

GET /unsubscribes

Returns unsubscribe events where the event was triggered from preferences centre, app, list unsubscribe (generated when the contact clicks the "unsubscribe" button in their email client), or link unsubscribe (generated when the contact clicks a link that is formatted for Ometria to recognise it).

since

The earliest date from which to fetch unsubscribe data. Following time format YYYY-MM-DDTH:I:S in UTC.

type
string
in
path
before

The latest date from which to fetch unsubscribe data. Following time format YYYY-MM-DDTH:I:S in UTC.

type
string
in
path
type

The type of unsubscribe event to return.

type
string
in
path
200 OK

An array of unsubscribe objects.

403 Forbidden

API key is not authorised to access this resource.

Response Example (200 OK)
[
  {
    "email_address": "email@example.com",
    "profile_id": "19e53-b37265-160",
    "reason": null,
    "reason_text": null,
    "timestamp": "2017-05-17 22:08:07+00",
    "type": "preferences_centre"
  }
]

Models

Contact: object

Describes an individual Contact listing record.

@type: string

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

@collection: string

The collection you want the contact to belong to.

id: string

The ID of this listing within the collection.

email: string

The email address of this listing.

phone_number: string

The mobile phone number for this contact, in E.164/International format (e.g. starting "+447...")

marketing_optin: string , x ∈ { EXPLICITLY_OPTEDOUT , NOT_SPECIFIED , EXPLICITLY_OPTEDIN }

The marketing opt in status of this contact.

customer_id: string

Your universal customer ID for this contact, if applicable.

@add_to_lists: array

An array of integers. For information on how to use, please read the actions documentation.

@remove_from_lists: array

An array of integers. For information on how to use, please read the actions documentation.

@force_optin: boolean

Either true or false. For information on how to use, please read the actions documentation.

@merge: boolean

Either true or false. For information on how to use, please read the actions documentation.

prefix: string

The title for this contact.

firstname: string

The first name for this contact.

middlename: string

The middle name for this contact.

lastname: string

The last name for this contact.

gender: string , x ∈ { m , f , o }

The gender for this contact. Currently supported values are "m" (Male), "f" (Female) and "o" (Other). The value "o" should be used when the contact's gender is known but it is not "m" or "f". If the contact's gender is unknown then the field "gender" should not be included.

date_of_birth: string (date)

The date of birth for this contact. Following ISO 8601 date format YYYY-MM-DD.

country_id: string (2 chars)

The country for this contact. Following ISO 3166-1 alpha-2.

store_ids: array

An array of strings for which stores the customer belongs to.

timezone: string

String value as defined in the tz database.

properties: object

Custom key value pairs

timestamp_acquired: string (date-time)

Date and time in which the contact is said to have been 'acquired'. Only provide if known clearly. Following ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z

timestamp_subscribed: string (date-time)

Date and time in which the contact is said to have been 'subscribed'. Only provide if known clearly. Following ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z

timestamp_unsubscribed: string (date-time)

Date and time in which the contact is said to have been 'unsubscribed'. Only provide if known clearly. Following ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z

channels: object

Contact preferences across different communication channels.

Example
{
  "@add_to_lists": [
    1,
    2,
    3
  ],
  "@collection": "default",
  "@remove_from_lists": [
    4,
    5,
    6
  ],
  "@type": "contact",
  "channels": {
    "sms": {
      "allow_marketing": true,
      "allow_transactional": true,
      "dt_updated_marketing": "2015-01-02T09:00:00+00",
      "dt_updated_transactional": "2015-01-02T09:00:00+00"
    }
  },
  "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"
}

ContactCollection: object

Describes a collection of Contact listing records.

collection: string

The collection ID.

count: integer

The number of records belonging to the collection.

Example
{
  "collection": "default",
  "count": 43540
}

CustomEvent: object

Describes a custom event. One of "profile_id", "identity_email", "identity_account_id" is required.

@type: string

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

id: string

The id of the custom event

event_type: string

The type of the custom event

timestamp: string

The timestamp of the event following ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z.

properties: object

Properties to be used in the event. User defined.

profile_id: string

The profile ID of the contact on which to trigger this custom event.

identity_email: string

The email of the contact record on which to trigger this custom event.

identity_account_id: string

The contact id of the contact record on which to trigger this custom event.

Example
{
  "@type": "custom_event",
  "event_type": "whatever",
  "id": "xxxxxx",
  "identity_account_id": "",
  "identity_email": "",
  "profile_id": "xxxxx",
  "properties": {
  },
  "timestamp": "2017-05-01T14:00:00Z"
}

DataDeletionRequest: object

Describes a GDPR related data anonymization request

id: string

The request ID

comment: string

User supplied comment text included in the initial request

timestamp_created: string (date-time)

Date and time of request being filed. Following ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z.

timestamp_completed: string (date-time)

Date and time of request being processed. Following ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z.

action: string , x ∈ { anonymise }

The action to take on this individual's data. The only supported value currently is "anonymise"

summary: string

A textual summary of the records found and modified after processing.

source: object

A summary of where the request originated, e.g. from with the application or via API.

identities: array

A list of hashed email addresses that represent the identities of individuals processed in this request.

Example
{
  "action": "anonymise",
  "comment": "Some comment",
  "id": "a8c53a39-e0fc-462c-b5fa-907fe70a4174",
  "identities": [
    {
      "hashed_email": "3af31748a10ef8bd28ce7620c25fe18d@anonymous.ometria"
    }
  ],
  "source": {
    "api_request_id": "a8c53a39-e0fc-462c-b5fa-907fe70a4174",
    "origin": "api",
    "user": {
      "email": "user@user.com",
      "name": "A user"
    }
  },
  "summary": "1 contact record anonymised, 15 events anonymise",
  "timestamp_completed": "2017-02-04 10:18:12.833949+00",
  "timestamp_created": "2017-02-02 10:18:12.833949+00"
}

DataDeletionSubmission: object

GDPR related data anonymization request submission

email_address: string

Email address of individual who requested anonymization

comment: string

Optional user supplied comment text

action: string , x ∈ { anonymise }

The action to take on this individual's data. The only supported value currently is "anonymise"

Example
{
  "action": "anonymise",
  "comment": "Some comment",
  "email_address": "someone@domain.com"
}

List: object

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

@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 , x ∈ { READY , CREATING , UPDATING , ARCHIVED }

The status of the list.

type: string , x ∈ { 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 offset YYYY-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)

profile_id: string

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

email: 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 , x ∈ { 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"
}

Order: object

Describes an Order record.

@type: string

The value must be "order". This shows that this record represents an order object.

id: string
timestamp: string (date-time)

Date and time the order was placed on the site or in store. Following ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z.

grand_total: number (float)

The grand total of the order.

subtotal: number (float)

The subtotal of this order.

discount: number (float)

This value should be negative or 0. Not positive.

shipping: number (float)

The shipping cost of this order.

tax: number (float)

The tax amount of this order.

currency: string (3 chars)

The currency for this order. Following ISO 4217.

web_id: string

The web ID passed with through the JS tracker, this is only required if the value is different to the id.

status: string

Code representing the status of this order 'complete', 'pending', 'shipped' etc.

is_valid: boolean

Is this order considered valid and should be counted against revenue? Set to false to 'delete'.

customer: OrderCustomer
lineitems: object[]

Array of OrderLineItem objects representing the items in this order.

ip_address: string

IP address of visitor who placed order if known.

channel: string online

Channel of this order. E.g., 'online', 'instore', 'amazon' etc.

store: string

Code representing the store the order was placed in.

payment_method: string

Code representing payment method.

shipping_method: string

Code representing shipping method.

shipping_address: OrderAddress

Address this order was shipped to.

billing_address: OrderAddress

Address this order was billed to.

coupon_code: string

Coupon code applied to this order.

properties: object

Custom key / value pairs accessible in emails using this order object.

Example
{
  "@type": "order",
  "billing_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "channel": "online",
  "coupon_code": "FJ45-TJ5Y-5YK3-T894",
  "currency": "GBP",
  "customer": {
    "email": "john.smith@example.com",
    "firstname": "John",
    "lastname": "Smith"
  },
  "discount": -5,
  "grand_total": 96.4,
  "id": "123553",
  "ip_address": "127.0.0.1",
  "is_valid": true,
  "lineitems": [
    {
      "product_id": "SS14-059493",
      "properties": {
        "custom_key": "custom value"
      },
      "quantity": 2,
      "sku": "SS14-059493-S5",
      "total": 100,
      "unit_price": 50,
      "variant_options": [
        {
          "id": "large",
          "label": "Large",
          "type": "size"
        },
        {
          "id": "color-45",
          "label": "Blue",
          "type": "color"
        }
      ]
    }
  ],
  "payment_method": "card",
  "properties": {
    "custom_key": "custom value"
  },
  "shipping": 2,
  "shipping_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "shipping_method": "standard",
  "status": "complete",
  "store": "example.com/en",
  "subtotal": 83.33,
  "tax": 16.07,
  "timestamp": "2015-01-02T09:00:00+00",
  "web_id": "891743"
}

OrderAddress: object

Describes an Address.

city: string

The town or city of the address.

state: string

The state or county of the address.

postcode: string

The postcode or zipcode of the address.

country_code: string (2 chars)

The country for this address. Following ISO 3166-1 alpha-2.

Example
{
  "city": "London",
  "country_code": "GB",
  "postcode": "W1K 4TG",
  "state": "Greater London"
}

OrderCustomer: object

Describes the customer details attached to an Order.

id: string

The ID of the customer.

email: string

The email address of the customer.

firstname: string

The first name of the customer.

lastname: string

The last name of the customer

Example
{
  "email": "john.smith@example.com",
  "firstname": "John",
  "id": "546548",
  "lastname": "Smith"
}

OrderExtended: object

Describes an Order record.

@type: string

The value must be "order". This shows that this record represents an order object.

id: string
timestamp: string (date-time)

Time the order was placed on the site or in store. Following ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z.

totals: OrderExtendedTotals
web_id: string

The web ID passed with through the JS tracker, this is only required if the value is different to the id.

status: string

Code representing the status of this order 'complete', 'pending', 'shipped' etc.

is_valid: boolean

Is this order considered valid and should be counted against revenue? Set to false to 'delete'.

customer: OrderCustomer
lineitems: object[]

Array of OrderLineItem objects representing the items in this order.

ip_address: string

IP address of visitor who placed order if known.

channel: string online

Channel of this order. E.g., 'online', 'instore', 'amazon' etc.

store: string

Code representing the store the order was placed in.

payment_method: string

Code representing payment method.

shipping_method: string

Code representing shipping method.

shipping_address: OrderAddress

Address this order was shipped to.

billing_address: OrderAddress

Address this order was billed to.

coupon_code: string

Coupon code applied to this order.

properties: object

Custom key / value pairs accessible in emails using this order object.

Example
{
  "@type": "order",
  "billing_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "channel": "online",
  "coupon_code": "FJ45-TJ5Y-5YK3-T894",
  "customer": {
    "email": "john.smith@example.com",
    "firstname": "John",
    "lastname": "Smith"
  },
  "id": "123553",
  "ip_address": "127.0.0.1",
  "is_valid": true,
  "lineitems": [
    {
      "product_id": "SS14-059493",
      "properties": {
        "custom_key": "custom value"
      },
      "quantity": 2,
      "sku": "SS14-059493-S5",
      "totals": {
        "base": {
          "currency": "GBP",
          "discount": -4,
          "subtotal": 99,
          "tax": 0,
          "total": 95,
          "unit_price": 99
        },
        "local": {
          "currency": "USD",
          "discount": -9,
          "subtotal": 129,
          "tax": 0,
          "total": 120,
          "unit_price": 129
        }
      },
      "unit_price": 50,
      "variant_options": [
        {
          "id": "large",
          "label": "Large",
          "type": "size"
        },
        {
          "id": "color-45",
          "label": "Blue",
          "type": "color"
        }
      ]
    }
  ],
  "payment_method": "card",
  "properties": {
    "custom_key": "custom value"
  },
  "shipping_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "shipping_method": "standard",
  "status": "complete",
  "store": "example.com/en",
  "timestamp": "2015-01-02T09:00:00+00",
  "totals": {
    "base": {
      "currency": "USD",
      "discount": -10,
      "grand_total": 149,
      "shipping": 10,
      "tax": 20
    },
    "local": {
      "currency": "USD",
      "discount": -10,
      "grand_total": 149,
      "shipping": 10,
      "tax": 20
    }
  },
  "web_id": "891743"
}

OrderExtendedBaseTotal: object

The totals of this order represented in the base currency

currency: string (3 chars)

The base currency totals - as set for your account. Following ISO 4217

shipping: number (float)

The value of the shipping in the base currency

tax: number (float)

The value of the tax in the base currency

discount: number (float)

The value of the discount in the base currency as a negative number

subtotal: number (float)

The value of the subtotal in the base currency

grand_total: number (float)

The value of the grand total in the base currency

Example
{
  "currency": "USD",
  "discount": -10,
  "grand_total": 149,
  "shipping": 10,
  "tax": 20
}

OrderExtendedLineItemBaseTotal: object

The totals of this lineitem represented in the base currency

currency: string (3 chars)

The currency of the base lineitem totals - as set for your account. Following ISO 4217

unit_price: number (float)

The value of the unit price in the base currency

discount: number (float)

The value of the discount on the lineitem in the base currency as a negative number

refunded: number (float)

The total price of refunded products in this line item.

subtotal: number (float)

The subtotal of this lineitem in the base currency (after refunded amounts have been taken into consideration).

tax: number (float)

The tax of this lineitem in the base currency (after refunded amounts have been taken into consideration).

total: number (float)

The total price of this line item in the base currency (after refunded amounts have been taken into consideration).

Example
{
  "currency": "GBP",
  "discount": -4,
  "subtotal": 95,
  "tax": 0,
  "total": 95,
  "unit_price": 99
}

OrderExtendedLineItemLocalTotal: object

The totals of this lineitem represented in the local currency

currency: string (3 chars)

The currency of the local lineitem totals. Following ISO 4217

unit_price: number (float)

The value of the unit price in the local currency

discount: number (float)

The value of the discount on the lineitem in the local currency as a negative number

refunded: number (float)

The total price of refunded products in this line item.

subtotal: number (float)

The subtotal of this lineitem in the local currency (after refunded amounts have been taken into consideration).

tax: number (float)

The tax of this lineitem in the local currency (after refunded amounts have been taken into consideration).

total: number (float)

The total price of this lineitem in the local currency (after refunded amounts have been taken into consideration).

Example
{
  "currency": "USD",
  "discount": -9,
  "subtotal": 120,
  "tax": 0,
  "total": 120,
  "unit_price": 129
}

OrderExtendedLineItemTotals: object

The totals of the lineitem. This can be used to express the order value in a base currency and a local currency.

base: OrderExtendedLineItemBaseTotal
local: OrderExtendedLineItemLocalTotal
Example
{
  "base": {
    "currency": "GBP",
    "discount": -4,
    "total": 95,
    "unit_price": 99
  },
  "local": {
    "currency": "USD",
    "discount": -9,
    "total": 120,
    "unit_price": 129
  }
}

OrderExtendedLocalTotal: object

The totals of this order represented in the local currency

currency: string (3 chars)

The currency of the local totals. Following ISO 4217

shipping: number (float)

The value of the shipping in the local currency

tax: number (float)

The value of the tax in the local currency

discount: number (float)

The value of the discount in the local currency as a negative number

subtotal: number (float)

The value of the subtotal in the local currency

grand_total: number (float)

The value of the grand total in the local currency

Example
{
  "currency": "USD",
  "discount": -10,
  "grand_total": 149,
  "shipping": 10,
  "tax": 20
}

OrderExtendedTotals: object

The totals of the order in a base currency and a local currency.

base: OrderExtendedBaseTotal
local: OrderExtendedLocalTotal
Example
{
  "base": {
    "currency": "USD",
    "discount": -10,
    "grand_total": 149,
    "shipping": 10,
    "tax": 20
  },
  "local": {
    "currency": "USD",
    "discount": -10,
    "grand_total": 149,
    "shipping": 10,
    "tax": 20
  }
}

OrderLineItem: object

Describes an individual product line item added to an Order.

product_id: string

The ID of the product.

variant_id: string

The ID of the variant of the product (if applicable).

quantity: integer

The number of products in the line item (not inclusive of any refunded items).

sku: string

The SKU of the product.

unit_price: number (float)

The unit price of the product in this line item.

quantity_refunded: integer

The number of products refunded in the line item.

refunded: number (float)

The total price of refunded products in this line item.

subtotal: number (float)

The subtotal of this lineitem (after refunded amounts have been taken into consideration).

tax: number (float)

The tax of this lineitem (after refunded amounts have been taken into consideration).

total: number (float)

The total price of this line item (after refunded amounts have been taken into consideration).

discount: number (float)

Must be a negative number.

is_on_sale: boolean

Indicating whether the product was on sale when the order was placed.

variant_options: object[]

An array of OrderLineItemVariantOption objects.

totals: OrderExtendedLineItemTotals
properties: object

Custom key / value pairs accessible in emails using the related Order object.

Example
{
  "discount": -10,
  "is_on_sale": true,
  "product_id": "SS14-059493",
  "properties": {
    "custom_key": "custom value"
  },
  "quantity": 2,
  "sku": "SS14-059493-S5",
  "subtotal": 100,
  "tax": 0,
  "total": 100,
  "unit_price": 50,
  "variant_options": [
    {
      "id": "large",
      "label": "Large",
      "type": "size"
    },
    {
      "id": "color-45",
      "label": "Blue",
      "type": "color"
    }
  ]
}

OrderLineItemVariantOption: object

Describes the configurable options attached to a Lineitem.

type: string

The type of the variant option.

id: string

The id of the variant option.

label: string

The label of the variant option.

Example
{
  "id": "size:5",
  "label": "5",
  "type": "size"
}

Product: object

Describes a Product record.

@type: string

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

id: string

The id of the product.

title: string

Title of this product as displayed to customers.

is_variant: boolean

Whether or not this product record represents a variant product.

price: number (float)

Default display price (account default currency / store).

sku: string

The SKU of the product.

special_price_dt_from: string (date-time)

Optional. Datetime that the 'special price' is applicable from. Format YYYY-MM-DD HH:II:SS.

special_price_dt_to: string (date-time)

Optional. Datetime that the 'special price' is applicable until. Format YYYY-MM-DD HH:II:SS.

special_price: number (float)

Optional. Reduced price used in conjunction with special_price_dt_from and special_price_dt_to.

is_active: boolean

Is this product considered active on the site. E.g. is it visible and (in principle) buyable? Please use "is_in_stock" to indicate whether a product is in stock or not.

is_in_stock: boolean

Is this product in stock?

url: string

URL of the product's page.

image_url: string

URL of the product's image.

attributes: array

Array of ProductAttribute objects.

listings: array

Array of ProductListing objects used to work out which stores this product is available in and any store specific details.

properties: object

Custom key / value pairs accessible in emails using this product object

Example
{
  "@type": "product",
  "attributes": [
    {
      "id": "category:womens",
      "label": "Womens",
      "type": "category"
    },
    {
      "id": "style:casual",
      "label": "Casual",
      "type": "style"
    }
  ],
  "id": "12345",
  "image_url": "http://www.example.com/product.jpg",
  "is_active": true,
  "listings": [
    {
      "currency": "EUR",
      "image_url": "http://www.example.com/fr/product.jpg",
      "is_active": true,
      "price": 50,
      "store": "example.com/fr",
      "title": "Produit d'essai",
      "url": "http://www.example.com/fr/product.html"
    },
    {
      "currency": "EUR",
      "image_url": "http://www.example.com/de/product.jpg",
      "is_active": false,
      "price": 50,
      "store": "example.com/de",
      "title": "Das Product",
      "url": "http://www.example.com/de/product.html"
    }
  ],
  "price": 50,
  "properties": {
    "custom_key": "custom value"
  },
  "sku": "FHSG-2738-FHI",
  "special_price": 45,
  "special_price_dt_from": "2015-03-02T09:00:00+00",
  "special_price_dt_to": "2015-01-02T09:00:00+00",
  "title": "Test Product",
  "url": "http://www.example.com/product.html"
}

ProductAttribute: object

Describes an attribute attached to a Product.

type: string

The type of the attribute.

id: string

The id of the attribute.

label: string

The label of the attribute.

Example
{
  "id": "category:womens",
  "label": "Womens",
  "type": "category"
}

ProductListing: object

Describes an individual store listing for a product.

title: string

The title of the product.

price: number (float)

The price of the product.

store: string

Code representing the store the product belongs to.

currency: string (3 chars)

The currency for this product listing. Following ISO 4217.

is_active: boolean

Is this product considered active on the site. E.g. is it visible and buyable?

special_price: number (float)

A discounted price for this product, used in connection with special_price_dt_from and special_price_dt_to on the parent product object.

url: string

The link to this product listing.

image_url: string

The link to an image of this product.

Example
{
  "currency": "EUR",
  "image_url": "http://www.example.com/fr/product.jpg",
  "is_active": true,
  "price": 59.99,
  "store": "example.com/fr",
  "title": "Produit d'essai",
  "url": "http://www.example.com/fr/product.html"
}

Profile: object

Describes an Ometria contact profile.

@type: string

The value must be "profile". This shows that this record is a profile object.

id: string

The ID of this profile record.

email: string

The email address of this contact profile.

name: string

The name of this contact profile.

lifecycle_status: string , x ∈ { LEAD , ACTIVE , AT_RISK , LAPSED }

The lifecycle status of this contact profile.

seen: boolean

Whether the contact profile has been seen on your website. Using the identify method in the JS tracker.

customer_id: string

The customer ID of this contact profile.

firstname: string

The first name of this contact profile.

middlename: string

The middle name of this contact profile.

lastname: string

The last name of this contact profile.

prefix: string

The prefix of this contact profile.

suffix: string

The suffix of this contact profile.

country: string (2 chars)

The country ID of this contact profile. Following ISO 3166-1 alpha-2.

gender: string , x ∈ { m , f , o }

The gender for this contact profile.

tags: string[]

Custom tags assigned to this profile in the Ometria UI.

properties: object

Custom key / value pairs of this contact profile.

date_of_birth: string (date)

The date of birth for this contact. Following ISO 8601 date format YYYY-MM-DD.

marketing_optin: boolean

TRUE if this contact has explicitly opted in. FALSE if they have explicitly opted out. NULL otherwise.

stats: ProfileStats
dates: ProfileDates
identities: ProfileIdentities
lists: ProfileLists
Example
{
  "@type": "profile",
  "country": null,
  "customer_id": "55555",
  "date_of_birth": "1984-04-22",
  "dates": {
    "acquired": "2014-11-01T15:34:35+00:00",
    "first_purchase": "2015-02-01T05:44:55+00:00",
    "first_seen": "2014-12-01T05:44:55+00:00",
    "last_purchase": "2015-02-01T05:44:55+00:00",
    "last_seen": "2015-02-01T05:44:55+00:00"
  },
  "email": "bob22@example.com",
  "firstname": null,
  "gender": "m",
  "id": "2695-c473e2-4aaf58",
  "identities": [
    {
      "id": "bob22@example.com",
      "type": "email"
    }
  ],
  "lastname": "smith111",
  "marketing_optin": null,
  "middlename": null,
  "name": "smith111",
  "prefix": null,
  "properties": {
    "custom_key": "custom value"
  },
  "seen": false,
  "stats": {
    "aov": 99.17,
    "orders": 1,
    "orders_attempted": 1,
    "revenue": 99.17,
    "total_items": 5,
    "visits": 20
  },
  "suffix": null,
  "tags": [
    "Attended VIP event 2017"
  ]
}

ProfileDates: object

Contains date / time information of a profile

first_seen: string (date-time)

The date time when this contact was first seen.

last_seen: string (date-time)

The date time when this contact was last seen.

first_purchase: string (date-time)

The date time when this contact first placed an order.

last_purchase: string (date-time)

The date time when this contact last placed an order.

acquired: string (date-time)

The date time when this contact was acquired.

marketing_optin: string (date-time)

The date time when this contact opted in to receive marketing emails.

marketing_optout: string (date-time)

The date time when this contact opted out to no longer receive marketing emails.

Example
{
  "acquired": "2014-11-07T15:34:35+00:00",
  "first_purchase": "2015-02-01T05:44:55+00:00",
  "first_seen": "2014-12-01T05:44:55+00:00",
  "last_purchase": "2015-02-01T05:44:55+00:00",
  "last_seen": "2015-02-01T05:44:55+00:00",
  "marketing_optin": "2014-11-09T15:34:35+00:00",
  "marketing_optout": null
}

ProfileIdentities: object[]

Contains identity information used to construct the profile

object
type: string
id: string
Example
[
  {
    "id": "bob22@example.com",
    "type": "email"
  }
]

ProfileLists: object[]

Contains the saved segments (lists) that a profile belongs to.

object
id: string

The ID of the list

title: string

The title of the list

type: string , x ∈ { STATIC , DYNAMIC }
Example
[
  {
    "id": 123,
    "title": "Title of the list",
    "type": "STATIC"
  }
]

ProfileStats: object

Contains numeric stats of a profile.

orders: number

Number of valid orders this profile has placed.

orders_attempted: number

Number of orders attempted by this contact profile (this includes valid as well as invalid orders).

total_items: number

Number of items purchased.

aov: number (float)

Average order value of this contact profile.

revenue: number (float)

Total revenue for this contact profile.

visits: number

Total number of visits for this contact profile.

Example
{
  "aov": 49.72,
  "orders": 2,
  "orders_attempted": 3,
  "revenue": 99.44,
  "total_items": 5,
  "visits": 20
}

PushError: object

Describes an individual error listing

request_id: string

The id of the request.

record_type: string

The type of the pushed record.

record_id: string

The id of the pushed record.

record: object

Copy of the pushed record which raised an error.

timestamp: string (date-time)

Datetime that the record was received. Format YYYY-MM-DDThh:mm:ss+Z.

message: PushErrorMessage
Example
{
  "message": {
    "error_message": "not a valid value",
    "error_path": "root > gender"
  },
  "record": {
    "@source": "api",
    "@type": "contact",
    "account": 239,
    "country_id": "GB",
    "customer_id": "7898734",
    "date_of_birth": "1985-01-05",
    "email": "john.smith@example.com",
    "firstname": "John",
    "gender": 12,
    "id": "123456",
    "lastname": "Smith",
    "marketing_optin": "EXPLICITLY_OPTEDIN",
    "middlename": "Fredrick",
    "prefix": "Mr",
    "properties": {
      "nickname": "Johnny",
      "number_of_cats": 4
    },
    "timestamp_acquired": "2015-01-02"
  },
  "record_id": "123456",
  "record_type": "contact",
  "request_id": "ed926048-52af-11e7-aa8c-0a3dc0ca7bee",
  "timestamp": "2017-06-16 16:22:06.705677+00"
}

PushErrorMessage: object

Describes what value is not correct and why

error_message: string

Description of the error.

error_path: string

Location of the error within the pushed record.

Example
{
  "error_message": "Value must be at least 1 characters.",
  "error_path": "root > attributes[1] > id"
}

PushRequest: object

An array of contact/order/product records.

Example
[
  {
    "@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",
    "prefix": "Mr",
    "properties": {
      "nickname": "Johnny",
      "number_of_cats": 4
    },
    "timestamp_acquired": "2015-01-02T09:00:00+00"
  },
  {
    "@type": "contact",
    "country_id": "US",
    "customer_id": "524323",
    "date_of_birth": "1990-04-12",
    "email": "jane.doe@example.com",
    "firstname": "Jane",
    "gender": "f",
    "id": "456",
    "lastname": "Doe",
    "marketing_optin": "EXPLICITLY_OPTEDOUT",
    "prefix": "Miss",
    "timestamp_acquired": "2012-05-01T23:00:00+00"
  }
]

PushResponse: object

The outcome of a push request.

status: string , x ∈ { OK , ERROR }

Status of the request

request_id: string

ID of the request

accepted: number

Number of records accepted

rejected: number

Number of records rejected, due to invalid format or data

skipped: number

Number of records skipped, due to duplication

Example
{
  "accepted": 1,
  "rejected": 0,
  "request_id": "c2da7180-52b2-11e7-92d6-0a3dc0ca7bee",
  "skipped": 0,
  "status": "OK"
}

TransactionalEmail: object

Describes a Transactional Email record.

subject: string

The subject to be used in the email.

to: TransactionalEmailAddress
from: TransactionalEmailAddress
reply_to: TransactionalEmailAddress
transactional: boolean

Whether this email should be considered transactional or not.

stream: string default

A string that can be made up for tracking purposes.

profile_id: string

Accepts a profile ID and this will make profile information available as dynamic content to be loaded into the email.

template_id: integer

The ID of the HTML email template to be used.

content: TransactionalEmailContent
data: object {}

Data passed in this object will be made available as dynamic content, available to be merged into the template before sending.

sandbox: boolean

When set to true, the email will be processed but not sent. To be used during testing.

Example
{
  "data": {
  },
  "from": {
    "email": "j.smith@example.com",
    "name": "John Smith"
  },
  "profile_id": "",
  "reply_to": {
    "email": "j.smith@example.com",
    "name": "John Smith"
  },
  "sandbox": true,
  "stream": "87tgHafe",
  "subject": "Email Subject",
  "template_id": 3,
  "to": {
    "email": "j.smith@example.com",
    "name": "John Smith"
  },
  "transactional": true
}

TransactionalEmailAddress: object

Describes an Email Address.

name: string

Name of the recipient.

email: string

Email of the recipient.

Example
{
  "email": "j.smith@example.com",
  "name": "John Smith"
}

TransactionalEmailContent: object

Describes the Email Content.

html: string

HTML version of the email.

text: string

Text version of the email.

Example
{
  "html": "<html><head></head><body>Email content</body></html>",
  "text": "Email content"
}

Unsubscribes: object

Describes an Unsubscribe record.

profile_id: string

The profile id of the contact whom has unsubscribed.

email_address: string

The email address of the contact whom has unsubscribed.

type: string , x ∈ { preferences_centre , app , list_unsubscribe , link_unsubscribe }

The type of unsubscribe event. This indicates where the contact unsubscribed (e.g., "preferences_centre").

timestamp: string (date-time)

The timestamp of the unsubscribe event.

reason: string

The reason given for unsubscribing.

reason_text: string

The reason provided for unsubscribing in the free-text field.

Example
{
  "email_address": "email@example.com",
  "profile_id": "19e53-b37265-160",
  "reason": null,
  "reason_text": null,
  "timestamp": "2017-05-17 22:08:07+00",
  "type": "preferences_centre"
}