Introduction

This document provides details of the Contact API. It is recommended that you read both the Data API Introduction page and the Ometria Data Architecture pages before integrating with Ometria. The easiest way to add contact data to Ometria is to use the Push API and the Contact API should only be used for specific cases.

Contents

About The Contact API

The Contact API provides methods to list the different collections (which can be viewed as sources of data), retrieve lists of contacts, retrieve an individual contact and create a new contact. A contact is a child object of a profile. Should you need the profile, use the Profile API.

Customer IDs / Account IDs

It is often the case that a retailer will have one unique customer / account identifier that they would like used in the primary reporting (for example row ID from the ecommerce customer database). Each contact can optionally supply a customer_id which would be this value. This value is also supplied in the contacts records when an order is placed by a registered customer (e.g. not a guest checkout) and is used to connect the profile record and the order.

This is different to a contact listing ID in that a profile may have many "contact listings" (with multiple contact IDs) but only one "customer ID" or "account ID".

Note: It's very important that ID's sent to the Ometria system do not contain Personally Identifiable Information (PII) (such as email address, phone number or name).

Contacts and Profiles

Records about people (customers / contacts / leads / subscribers) are supplied as 'contacts' records. Contacts are organised into 'collections'. For example you may have a 'customers' collection (customer records from your ecommerce platform) and a 'subscribers' collection (contact records from your ESP). Each record in a collection is uniquely identified by a string ID.

In this case it may be that the same person exists in each list (or even more than once in each collection). Ometria will attempt to merge these contacts records into a single 'profiles' record (based on customer_id and then email address). Thus a single profile record may have several contacts records attached.

You cannot write profile records directly as they are automatically clustered by the Ometria system.

It is recommended that contacts from different sources should be passed into Ometria with different collections. This will help to ensure that data on the record is not over-ridden by missing data from another source.

Contact listings Priority

When merging contact records to create a profile, it is sometimes the case that there will be varying parameters on the contact records. When this happens, Ometria will use the following two rules of priority to determine which value to assign to the profile:

Standard Rules of Priority
  1. Preferences centre
  2. API, App, CSV
  3. Ometria Form
  4. Importer (Magento or Shopify)
  5. 3rd party sync

Note:

  • If there are two contact records with the same level of priority, then the varying parameters from the most recent contact record will will be used.
  • firstname and lastname parameters will always be taken from the same contact record.

Marketing Opt-in Rules of Priority

These rules only apply only to a contact's marketing_optin value.

The order of preference

  1. Any Ometria controlled source (eg. Preference centre, Platform, Ometria Form, CSV Uploader)
  2. Any Client controlled source (eg. API, Magento Importer)
  3. Any 3rd Party controlled source (eg. Mailchimp)

Add to / Remove from lists

This action can be used on contacts only and is used to add contacts to static lists and/or to remove contacts from static lists.

This action is added as a top level parameter on the contact record and only needs to be sent once to perform the action; you do not need to send the lists that you want the contact to belong to each time.

Finding the list IDs

First login to the platform.

Then go to the saved segments page (from the navigation bar: CUSTOMER > SAVED SEGMENTS).

The list IDs are shown on the left hand side of the table.

Please note, the list IDs are unique across Ometria and so you will need to find the list IDs for the staging account and live account.

Example

In this example we are adding the contact record with id GE9834 to the lists with IDs 1, 2, and 3 before and removing them from the lists with IDs 4, 5, and 6.

{
    "@type": "contact",
    "id": "GE9834",
    "email": "test@example.com",
    "@add_to_lists": [1, 2, 3],
    "@remove_from_lists": [4, 5, 6]
}

Remove From Lists

This action can be used on contacts only and is used to add contacts to static lists and/or to remove contacts from static lists.

This action is added as a top level parameter on the contact record and only needs to be sent once to perform the action; you do not need to send the lists that you want the contact to belong to each time.

Finding the list IDs

First login to the platform.

Then go to the saved segments page (from the navigation bar: CUSTOMER > SAVED SEGMENTS).

The list IDs are shown on the left hand side of the table.

Please note, the list IDs are unique across Ometria and so you will need to find the list IDs for the staging account and live account.

Example

In this example we are adding the contact record with id GE9834 to the lists with IDs 1, 2, and 3 before and removing them from the lists with IDs 4, 5, and 6.

{
    "@type": "contact",
    "id": "GE9834",
    "email": "test@example.com",
    "@add_to_lists": [1, 2, 3],
    "@remove_from_lists": [4, 5, 6]
}

Force Optin

This action can be used on contacts only and is used to force the marketing_optin value passed in the same contact record. This action is added as a top level parameter on the contact record and only needs to be sent once to perform the action.

When @force_optin is set to true, this will override the default marketing optin priority.

Example

In this example we are force opting in the contact.

{
    "@force_optin": true
    "marketing_optin": "EXPLICITLY_OPTEDIN"
}

Merge

Merge can be used with contact records to combine the record being sent with an existing record of the same type, id and collection in Ometria.

When @merge is passed as true on a new record, any parameters which are not set will be copied from the existing record in Ometria. The new record will then overwrite the existing record.

Example

{
    "@merge": true
}

Contact Methods

List Collections

List Contacts

Get Contact Listing

Create Contact

Contact Objects

Contact Object

Contact Collection


List Collections

Path

GET /contacts

Description

List contact collections along with counts of records in each collection

Request Parameters

limit Number of items to return. Max 250.
typestring (default: "10")
inquery
offset

Index of first record.

typestring (default: "0")
inquery

Response

200 OK ContactCollection 

Collection objects

403 Forbidden

API key is not authorised to access this resource

Response Example (200 OK)

Response Example (200 OK)

[

  {

    "collection": "default",

    "count": 43540

  }

]



List Contacts

Path

GET /contacts/{collection}

Description

List Contacts in Collection with optional filters

Request Parameters

collection

ID of collection to fetch.

typestring
inpath
limit

Number of items to return. Max 250.

typestring (default: "10")
inquery
offset

Index of first record.

typestring (default "0")
inquery

Response

200 OK Contact 

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

    "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

Path

GET /contacts/{collection}/{contact_id}

Description

Return a single Contact record

Request Parameters

collection

ID of collection to which the contact belongs.

typestring
inpath
contact_id

ID of contact to fetch.

typestring
inpath

Response

200 OK Contact

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

  "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

Path

POST /contacts/{collection}/{contact_id}

Description

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

Request Body

Contact 

Contact object

Request Parameters

collection

ID of collection to create or update.

typestring
inpath
contact_id

ID of contact to create or update.

typestring
inpath

Request Example

{

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

}

Response

200 OK

Contact object successfully created or updated

403 ForbiddenAPI key is not authorised to access this resource

Contact: object

Describes an individual Contact listing record.

ValueTypeDescriptionRequired
@typestringThe value must be "contact". This shows that this record represents a contact object.Required
@collectionstringThe collection you want the contact to belong to. Collection and ID provide a unique reference for the contact record. Collection can be used to debugging If not passed, Collection will be automatically added as "default"
idstring

The contact ID of this listing within the collection. See Ometria Data Architecture for an explanation on how to use contact ID.


ID must not be PII data or email address.

Required
emailstring

The email address of this listing.

Required
phone_numberstring

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


marketing_optinstring { EXPLICITLY_OPTEDOUT , NOT_SPECIFIED ,EXPLICITLY_OPTEDIN }

The marketing opt in status of this contact.


customer_idstring

Your universal customer ID for this contact, if applicable. 


The customer ID is optional and should only be used where you have one persistent key across all of your data sources that uniquely identifies an individual customer.


Customer ID must not be PII data or email address.


@add_to_listsarray

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


@remove_from_listsarray

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


@force_optinboolean

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


@mergeboolean

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


prefixstring

The title for this contact.


firstnamestring

The first name for this contact.


middlenamestring

The middle name for this contact.


lastnamestring

The last name for this contact.


genderstring { 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_birthstring (date)

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


country_idstring (2 chars)

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


store_idsarray

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


timezonestring

String value as defined in the tz database.


propertiesobject

Custom key value pairs


timestamp_acquiredstring

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 format: date-time


Note: Not providing the timestamp acquired may affect reporting.


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


Note: Not providing the timestamp subscribed may affect automation campaigns that depend on a date for triggering.

Note: Not providing the timestamp subscribed may affect reporting.


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

Note: Not providing the timestamp unsubscribed may affect reporting.


Example

{

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

}


ContactCollection: object

Describes a collection of Contact listing records.

ValueTypeDescriptionRequired
collectionstring

The collection ID.


countintegerThe number of records belonging to the collection.

Example

{

  "collection": "default",

  "count": 43540

}