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):

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.

The queue has a maximum backlog of 50k, so if more than 50k records are waiting to be processed, you'll get a 429 HTTP response status code.

You can use the headers X-QueueSize-Limit returned in the response to see your current backlog and X-QueueSize-Remaining to check your remaining allowance.

Data sorting behaviour

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

Null values

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

"lastname": null