canonical: https://jentic.com/apis/ometria.com/ometria

# Ometria Data API

Jentic publishes the only available OpenAPI specification for Ometria Data API, keeping it validated and agent-ready. The Ometria Data API is the integration layer for Ometria's customer data and marketing platform, enabling brands to push customer, product, order, and event records into Ometria and to retrieve segmented data for downstream use. It exposes 34 endpoints covering bulk push, products, orders, contact collections, custom events, profile management with a profile-merge job system, list (segment) export, transactional email send, and unsubscribes/data-deletion request lookup. Authentication uses the X-Ometria-Auth header.

## For AI agents

Push customer, product, order, and event data into Ometria's marketing platform and pull back segments, profiles, and unsubscribes for downstream campaigns.

## Scope

Does not handle campaign content design, A/B test orchestration, or paid-media buying - use for data ingestion, segment export, and transactional sends only.

## Capabilities

- Push customer, product, order, and custom event records via the bulk /push endpoint
- Inspect /push-errors to diagnose rejected records from the last bulk import
- Retrieve products and orders by ID for downstream catalogue sync
- Read contact collections and individual contacts by ID for personalisation
- Run profile merge jobs to deduplicate customer records and track job status
- Export the contact membership of a segment via `/lists/{list_id}/contacts/export`
- Send a transactional email through `/transactional-email/send`

## Use cases

### Order and Customer Sync from E-Commerce

An e-commerce platform pipes new orders, customers, and product updates into Ometria using POST /push as the single ingestion endpoint, then polls GET /push-errors to surface rejected records back to the data team. This keeps the marketing platform in sync without bespoke per-resource endpoints.

Example prompt: POST a batch of 200 mixed records (customers, orders, products) to /push, then GET /push-errors to inspect any failures and re-push corrected records.

### Segment Activation for Email Campaigns

Marketing teams build segments (lists) inside Ometria and use GET `/lists/{list_id}/contacts/export` to download segment membership for activation in adjacent channels (paid social audiences, direct mail). The export endpoint is built for scale and returns the full membership rather than a paginated trickle.

Example prompt: GET /lists to find the 'cart-abandoners' segment ID, then GET `/lists/{list_id}/contacts/export` to pull the full membership.

### Profile Deduplication via Merge Jobs

When the same customer appears under two profiles (different emails, same person), POST /merge-profile schedules a merge job that consolidates them. GET /merge-profile lists running jobs and GET `/merge-profile/{job_id}` returns the status of a specific job. This is the recommended path over manual SQL fixups in the underlying data.

Example prompt: POST /merge-profile with two profile IDs, then poll GET `/merge-profile/{job_id}` until status is complete.

### AI Agent Marketing Operations

An AI agent integrated through Jentic can ingest a CSV of new customers from a one-off campaign, push them via /push, monitor /push-errors, and then trigger a transactional welcome email - all without seeing the X-Ometria-Auth header. Jentic stores the credential and returns scoped operation handles only.

Example prompt: Search Jentic for 'push customers to ometria', load /push, ingest 500 records, then call `/transactional-email/send` to dispatch a welcome email to each.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/push` | Bulk-push records (customers, orders, products, events) |
| GET | `/push-errors` | List rejected records from recent pushes |
| GET | `/lists/{list_id}/contacts/export` | Export segment membership |
| POST | `/merge-profile` | Run a profile-merge job |
| POST | `/transactional-email/send` | Send a transactional email |
| GET | `/unsubscribes` | List unsubscribes for compliance |

## Key resources

- **Push** — Bulk-ingest customers, products, orders, and custom events; inspect rejected records via push-errors.
- **Products** — List products and retrieve a product by ID.
- **Orders** — List orders and retrieve an order by ID.
- **Contacts and Profiles** — Read contact collections, individual contacts, and profile records; run profile-merge jobs to dedupe.
- **Lists** — List segments, retrieve a list by ID, get list changes, and export list membership.
- **Transactional Email** — Send a transactional email via `/transactional-email/send.`
- **Compliance** — List unsubscribes and data-deletion requests for GDPR reporting.

## Why Jentic

- **Setup:** Wiring the Ometria Data API by hand means setting up its X-Ometria-Auth header, targeting the api.ometria.com/v2 host, and navigating 34 endpoints across data push, segment export, and transactional sends yourself. Through Jentic you install once, import Ometria from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** Ometria puts the list id in the URL path (`/lists/{list_id}/contacts/export`), so a rule can pin your agent to exporting one list, and across the wider surface you limit it to the operations it needs, such as reading push errors or unsubscribes. You choose the operations it may call, so a data push or transactional send is not included unless you add it.
- **Credential handling:** Your Ometria API key is stored once, encrypted, by your own Jentic One instance and injected into the X-Ometria-Auth header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'push customers to Ometria' or 'export a segment', and Jentic returns the matching operation, often /push or `/lists/{list_id}/contacts/export`, with its full input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Klaviyo API** — Email and SMS marketing platform with deep e-commerce integrations.
- **Shopify Admin API** — Source store data that gets pushed into Ometria for personalisation.
- **Segment API** — Customer data pipeline that fans events into Ometria and other tools.

## FAQ

### Why is there no official OpenAPI spec for Ometria Data API?

Ometria does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Ometria Data API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Ometria Data API use?

Every request must include the X-Ometria-Auth header carrying an API key issued from the Ometria UI. Jentic stores this key encrypted in your Jentic One instance and injects it on each call, so agents never see the raw header.

### Can I send transactional emails through the Ometria Data API?

Yes. POST `/transactional-email/send` dispatches a one-off transactional email using a template configured in Ometria. This is separate from the campaign system and is intended for receipts, password resets, and order confirmations.

### What are the rate limits for the Ometria Data API?

Rate limits are not declared in the OpenAPI spec but Ometria recommends pushing data in batches of up to 1,000 records per /push call. Use /push-errors to detect rejections rather than retrying full batches blindly.

### How do I dedupe two customer profiles through Jentic?

Search Jentic for 'merge ometria profiles', load POST /merge-profile, and pass the two profile IDs. Then poll GET `/merge-profile/{job_id}` to confirm completion.

### Is the Ometria Data API rate-limited per endpoint?

The spec does not differentiate per-endpoint limits. The /push endpoint is built for bulk ingestion (preferred for high-volume writes) while individual `/products/{id}` and `/orders/{id}` reads are intended for low-frequency lookups.

### Can I limit what my agent is allowed to do with the Ometria Data API?

Yes. Because you run Jentic One yourself, your own rules decide which of the 34 Ometria operations the agent may call and which credential it may use, so a bulk POST /push or a POST `/transactional-email/send` is excluded unless you explicitly add it. Since Ometria puts the list id in the URL path at `/lists/{list_id}/contacts/export`, you can pin the agent to exporting a single segment, or restrict it to read-only operations such as GET /push-errors and GET /unsubscribes. The API key stays with your instance and is never exposed to the agent.