Contact API

This document provides details of the Contact API.

We recommend 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 - the contact API should only be used for specific cases.

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 - it represents the contact listing which makes up a customer 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 contact's 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 IDs sent to Ometria do not contain personally identifiable information (PII) (such as email address, phone number or name). This is in case the ID is exposed publicly.

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 Customer > Saved segments

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

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 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, it overrides 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

Variable	Description
limit	Number of items to return. Max 250.
type	string (default: "10")
in	query
offset	Index of first record.
type	string (default: "0")
in	query

Response

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

Variable	Description
collection	ID of collection to fetch.
type	string
in	path
limit	Number of items to return. Max 250.
type	string (default: "10")
in	query
offset	Index of first record.
type	string (default "0")
in	query

Response

Response	Description
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",
    "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"
      }
    },
    "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

Variable	Description
collection	ID of collection to which the contact belongs.
type	string
in	path
contact_id	ID of contact to fetch.
type	string
in	path

Response

Response	Description
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",
    "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"
      }
    },
    "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

Type	Description
Contact	Contact object

Request Parameters

Variable	Description
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",
    "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",
    "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"
      }
    },
    "properties": {
      "nickname": "Johnny",
      "number_of_cats": 4
    },
    "store_ids": [
      "gb"
    ],
    "timestamp_subscribed": "2015-01-02T09:00:00+00"
  }
]

Response

Response	Description
200 OK	Contact object successfully created or updated
403 Forbidden	API key is not authorised to access this resource

Contact: object

Describes an individual Contact listing record.

Value	Type	Description	Required
@type	string	The value must be "contact". This shows that this record represents a contact object.	Required
@collection	string	The 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"
id	string	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
email	string	The email address of this listing.	Required
phone_number	string	The mobile phone number for this contact, in E.164/International format (e.g. starting "+447...") See further information on uploading phone numbers below.
marketing_optin	string { 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.  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_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 { 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	The tz database name for your timezone. E.g. The tz database name for GB is 'Europe/London'.
properties	object	Custom fields within your contact profile defined by you, e.g. subscription programmes, due dates etc. The following field types are available: String Integer Decimal  Date Note: The custom field ID should be lower case and contain no spaces, e.g. skin_type, loyalty_tier.
timestamp_acquired	string	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_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 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.
channels	channels object	See below.

Channels object 

All fields are optional.

Field	Type	Description
sms	sms channel object	SMS related contact preferences

SMS channel object

The following fields have been introduced to support SMS marketing in Ometria.

All fields are optional

Currently Ometria only supports SMS for automation campaigns, not broadcast or transactional. 

Field	Type	Description
allow_marketing	Boolean	Allows marketing messages SMS (automation and broadcast). Note: For now, Ometria only supports SMS for automation campaigns.
allow_transactional	Boolean	Transactional messages SMS.  Note: For now, Ometria only supports SMS for automation campaigns.
dt_updated_marketing	String - date-time	Date and time the contact 'unsubscribed' - only provide if known. Use ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z
dt_updated_transactional	String - date-time	Date and time the contact 'unsubscribed' - only provide if known. Use ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z

Pushing phone numbers

Be aware that if you push a contact with a phone number which matches an existing phone number in your database, then the number will not be merged.

Example, if you push the following two records, one in January and one in February, with the same phone number:

Fields	Pushed January 2020	Pushed February 2020
id	1234	5678
email	customer1@gmail.com	customer2@hotmail.co.uk
phone_number	+447567890987	+447567890987

...then Ometria will only ingest the following information:

• id = 5678
• email = customer2@hotmail.co.uk

And not the phone number.

This is in order to avoid the duplication of phone numbers. 

There is currently no way to move phone numbers across or assign a phone number to the most recent profile.

ContactCollection: object

Describes a collection of Contact listing records.

Value	Type	Description	Required
collection	string	The collection ID.
count	integer	The number of records belonging to the collection.

Example

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