Ometria API introduction

Data API endpoint


The Ometria API is organised around the REST methodology, and it uses resource-oriented URLs, and common HTTP response codes to indicate API errors.


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.


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.


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


Good to know

The limits below are defaults - they can be adjusted to your needs depending on your Ometria plan and the scale of your database. Please contact your Customer Success Representative for more information.

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

Data API4 requests per second
Push endpoint8 requests per second (allows multiple records per request)
Transactional email API30 requests per second
GDPR anonymisation API6 requests per minute
Merge profiles with duplicate email and/or ID1 request per minute

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:

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