Ometria API introduction

Data API endpoint

https://api.ometria.com/v2

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.

Authentication

The header key is X-Ometria-Auth.

All requests must be sent with an API key in the request header.

See API Keys to find out how to generate a new API key in Ometria.

HTTPS

All requests to the Ometria API must be carried out via HTTPS on port 443.

Message encoding

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

Size limits

There is a 60KB limit per record across the data API (a request can have multiple records with 60KB each.)

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

There is a limit of 100 records per request.

Objects

An API call should only ever include one object type (i.e. contacts, orders, products or custom events).

You should never mix object types.

Rate limits

The Ometria API rate limits are as follows (per Ometria account):

📘

If you'd like to increase any of the API rate limits please get in touch with your Customer Success Representative.

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.

📘

The push endpoint is asynchronous, which means that records from the submitted batch are added to a queue to be processed.

Data sorting behaviour

Unless the orderby=timestamp_update query parameter is specified, results are sorted by their internal Ometria ID in ascending order.

Merge objects

You can use "@merge": true on any of our endpoints or push objects to partially update contact or product records and avoid overwriting existing fields.

See also:

• How to merge a product
• How to merge a contact record

Example product payload:

{
  "@type": "product",
  "id": "your_product_id",
  "title": "product_title",
  "price": 100.00,
  "@merge": true,
  ...
}

Null values

Passing null will delete any existing value in the field, e.g.:

"lastname": null