Data API introduction

Overview

This guide is designed to present a typical use case and will provide an overview of the steps involved in a custom integration.

If you need more help with your particular use case please contact us support by raising a ticket.

Contents

• About the Data API
• Integration Approach
• Data Conventions
• API Methods

About the Data API

Rest

The Ometria API is organised 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

See: Default rate limits

Size limits

There is a 60k byte limit per record for both our push API and REST endpoints. 

If you exceed this limit, you will see the following error message "Payload invalid: Record is too large".

Order behaviour

The Ometria API endpoints return results sorted by their internal Ometria ID in ascending order by default. This is unless the orderby=timestamp_update query parameter is specified, in which case results are returned sorted by datetime in ascending order. 

API Endpoint

https://api.ometria.com/v2

Integration Approach

There are typically two parts to a full Ometria integration:

• Ecommerce data API: allows orders, products and contact data to be pushed via a REST endpoint and should be used to import historic data in a batch run as well as to push new data and updates in realtime. In addition to data collected from your ecommerce platform, it is also possible to push data that has been collected offline (for example, from a POS system).

• Javascript tracking API: enables the collection of interaction data (e.g. product views), identification data and abandoned baskets. We will provide a Javascript tag that will make available a set of public methods that will need to be called on every page where an event occurs. This tag can often be inserted via your existing data layer and tag management solution if you have one.

First steps

We will provide you with your live and staging account links send you your account hash (for Javascript) and an access token (For Data API) for your staging account.

This will allow for testing of the validity of any data pushed to our system, before moving to the live account (for which there is a different account hash and access token).

Ecommerce data API

The Ometria API defines traditional REST endpoint for the main data objects we import (orders, products and contacts).

We also define a Push API that allows easier batch upload. For most use cases the Push API will be simpler to work with.

We use historic data to build a single customer view, helping to maximise each customer’s lifetime value. When working on the staging account, it is recommended to import test data that is representative of your production dataset; using this as an opportunity to test that the data you have pushed to the Ometria API is passed correctly.

The data format used for uploading historic data is the same as that which is used for the realtime updates and using the Push API it is possible to send 100 records at once. It is also advised to import your entire product catalogue to the staging server, for the same purpose of ensuring that the data is passed correctly to Ometria.

It is best practice to push an order, product or contact object to Ometria as soon as you consider that order, product or contact is created. Following on from this, any subsequent changes to the order, product or contact should be pushed in real time where possible.

When pushing orders it is possible to add the products object inside of the orders object, however we recommend that products are pushed separately from orders and that they are referenced inside of an order by using the product id.

Where your products have variations it is important to include variant_options in the line items of the order object. This has a number of advantages inside of the Ometria platform, including allowing us to better recommend products to your customers.

For the available API calls, See Ecommerce Data API.

Javascript tracking API

The Ometria Javascript API allows the collection of page view and other interaction events on your ecommerce store which can then be associated with contact profiles and used for orders and revenue attribution.

Integrating the Ometria Javascript API involves including the Ometria Javascript tag and calling certain methods depending on the type of page (e.g. product page) being viewed and also based on information about the visitor (e.g. are they logged in) and their basket contents.

See Javascript API.

Final stages

Once you are happy with the methods in place for pushing data and any issues have been resolved, we will generate an account hash and access token for your live account.

The access token in your requests to the ecommerce data API will need to be updated to your live account's access token and the account ID in the javascript tracking source will need to be updated to your live account's account ID.

Data Conventions

Null values

Entering null will populate a string field with null (i.e. empty), e.g.:

"lastname": null

 Passing null will delete a value in the field.

ID Fields

All ID fields in Ometria are string and cannot contain spaces.

API Methods

The following API methods are available in the Ometria Data API suite. It is recommended that you start with the Push API for adding contacts, orders and products to Ometria.