Ometria Profiles API
The Profiles API from Ometria — 4 operation(s) for profiles.
The Profiles API from Ometria — 4 operation(s) for profiles.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/ometria:ometria-profiles-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
version: 1.1.0
title: Ometria data Profiles API
description: 'Welcome to the Ometria API reference.
The Ometria API is organized 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
The Ometria API has a default rate limit of 4 requests per second per Ometria account. The /push/ endpoint allows 8 requests per second per Ometria account. If you expect to exceed this limit, please contact us.
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.'
contact:
name: Ometria
email: support@ometria.com
url: https://ometria.com
servers:
- url: https://api.ometria.com/v2
security:
- apikey: []
tags:
- name: Profiles
paths:
/profiles/:
get:
tags:
- Profiles
summary: Fetch list of profiles
description: Return profiles as a JSON array
parameters:
- name: limit
in: query
description: The number of records to fetch. Maximum 250.
required: false
schema:
type: integer
default: 10
- name: offset
in: query
description: Index of first record to fetch
required: false
schema:
type: integer
default: 0
- name: updateSince
in: query
description: Only return contacts that have been updated since this date.
schema:
type: string
format: date
- name: updateBefore
in: query
description: Only return contacts that have been updated before this date.
schema:
type: string
format: date
- name: createSince
in: query
description: Only return contacts that have been created since this date.
schema:
type: string
format: date
- name: createBefore
in: query
description: Only return contacts that have been created since this date.
schema:
type: string
format: date
- name: email
in: query
description: The email address of the profile to fetch.
required: false
schema:
type: string
- name: customerId
in: query
description: The customer ID of the profile to fetch.
required: false
schema:
type: string
- name: phoneNumber
in: query
description: The phone number of the profile to fetch. Plus signs (+) should be swapped with %2b
required: false
schema:
type: string
- name: profileHash
in: query
description: The profile hash of the profile to fetch.
required: false
schema:
type: string
responses:
'200':
description: List of profile objects
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Profile'
'403':
description: API key is not authorised to access this resource
'404':
description: List with specified ID was not found
operationId: getProfiles
x-operation-id-source: derived
/profiles/{profile_id}:
get:
tags:
- Profiles
summary: Fetch individual profile
description: Return profile as a JSON object
parameters:
- name: profile_id
in: path
description: The ID (hash) of the profile to fetch (eg 27f4-8337f0-002384af).
required: true
schema:
type: string
responses:
'200':
description: Return a single profile record
content:
application/json:
schema:
$ref: '#/components/schemas/Profile'
'403':
description: API key is not authorised to access this resource
'404':
description: Profile with specified ID was not found
operationId: getProfilesByProfileId
x-operation-id-source: derived
/merge-profile:
post:
tags:
- Profiles
summary: Merge profiles based on the provided identifiers
description: Merge customers_to_merge profiles into the survivor profile. Identifiers supplied here can be any identifier defined in your account's identity resolution configuration (e.g. `customer_id`, `profile_hash`, `email_address`, `phone_number`, or any custom extra identifier such as `loyalty_id`), as well as `profile_id` — the ID (hash) of the profile (e.g. `27f4-8337f0-002384af`).
requestBody:
required: true
description: profiles to merge, customers_to_merge will be merged into survivor
content:
application/json:
schema:
$ref: '#/components/schemas/MergeProfiles'
example:
survivor:
type: email_address
value: survivor@email.com
customers_to_merge:
- type: customer_id
value: ABC123
- type: profile_hash
value: 27f4-26e69b-0000007b
- type: email_address
value: customer@email.com
- type: phone_number
value: '+447123456789'
- type: profile_id
value: 27f4-8337f0-002384af
responses:
'202':
description: Merge profile job placed.
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: Status of the merge job.
job_id:
type: integer
description: The id of the job that was placed.
example:
status: Merge profile job placed
job_id: 1234
'400':
description: Invalid payload.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
example:
status: 400
type: about:blank
detail: Cannot merge a profile with itself
title: Bad Request
'403':
description: API key is not authorised to access this resource.
'404':
description: Profile not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
example:
status: 404
type: about:blank
detail: Profile not found
title: Not Found
'429':
description: Max in progress jobs per account reached.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
example:
status: 429
type: about:blank
detail: Too many merge jobs in progress
title: Too Many Requests
'500':
description: An error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
example:
status: 500
type: about:blank
detail: Internal Server Error
title: An error occurred
operationId: postMergeProfile
x-operation-id-source: derived
get:
tags:
- Profiles
summary: Get the status of merge jobs
description: Get the status of merge jobs.
parameters:
- name: limit
in: query
description: The limit for pagination purposes.
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: offset
in: query
description: The offset for pagination purposes.
required: false
schema:
type: integer
minimum: 0
default: 0
responses:
'200':
description: The statuses of the merge jobs.
content:
application/json:
schema:
type: object
properties:
offset:
type: integer
description: The offset used for pagination.
limit:
type: integer
description: The limit used for pagination.
job_count:
type: integer
description: The number of merge jobs returned.
total_job_count:
type: integer
description: The total number of merge jobs in the account.
jobs:
type: array
items:
$ref: '#/components/schemas/MergeProfileJobStatus'
example:
offset: 2
limit: 10
job_count: 3
total_job_count: 5
jobs:
- job_id: 12
status: finished
- job_id: 13
status: failed
- job_id: 14
status: in_progress
'400':
description: Invalid limit or offset.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
example:
status: 400
type: about:blank
detail: -1 is less than the minimum of 0
title: Bad Request
'403':
description: API key is not authorised to access this resource.
'500':
description: An error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
example:
status: 500
type: about:blank
detail: Internal Server Error
title: An error occurred
operationId: getMergeProfile
x-operation-id-source: derived
/merge-profile/{job_id}:
get:
tags:
- Profiles
summary: Get the status of a specific merge job
description: Get the status of a specific merge job.
parameters:
- name: job_id
in: path
description: The id of the merge job.
required: true
schema:
type: integer
responses:
'200':
description: The statuses of the merge jobs.
content:
application/json:
schema:
$ref: '#/components/schemas/MergeProfileJobStatus'
example:
job_id: 1234
status: finished
'403':
description: API key is not authorised to access this resource.
'404':
description: Merge job not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
example:
status: 404
type: about:blank
detail: Merge job 15 not found
title: Bad Request
'500':
description: An error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
example:
status: 500
type: about:blank
detail: Internal Server Error
title: An error occurred
operationId: getMergeProfileByJobId
x-operation-id-source: derived
components:
schemas:
ProfileStats:
type: object
description: Contains numeric stats of a profile.
properties:
orders:
type: number
description: Number of valid orders this profile has placed.
orders_attempted:
type: number
description: Number of orders attempted by this contact profile (this includes valid as well as invalid orders).
total_items:
type: number
description: Number of items purchased.
aov:
type: number
description: Average order value of this contact profile.
format: float
revenue:
type: number
description: Total revenue for this contact profile.
format: float
visits:
type: number
description: Total number of visits for this contact profile.
example:
orders: 2
orders_attempted: 3
total_items: 5
aov: 49.72
revenue: 99.44
visits: 20
MergeProfiles:
type: object
properties:
survivor:
$ref: '#/components/schemas/ProfileIdentifier'
customers_to_merge:
type: array
items:
$ref: '#/components/schemas/ProfileIdentifier'
minItems: 1
maxItems: 5
uniqueItems: true
MergeProfileJobStatus:
type: object
properties:
job_id:
type: integer
description: The id of the merge job.
status:
type: string
description: The status of the merge job.
enum:
- in_progress
- completed
- failed
Profile:
title: Profile
type: object
description: Describes an Ometria contact profile.
properties:
'@type':
type: string
description: The value must be "profile". This shows that this record is a profile object.
id:
type: string
description: The ID (profile hash) of this profile record, eg 27f4-f0b281-00003039. This is the `profile_hash` accepted by `/field-forget` and `/merge-profile`, and by the `profileHash` parameter of `GET /profiles/`.
email:
type: string
description: The email address of this contact profile.
name:
type: string
description: The name of this contact profile.
lifecycle_status:
type: string
description: The lifecycle status of this contact profile.
enum:
- LEAD
- ACTIVE
- AT_RISK
- LAPSED
seen:
type: boolean
description: Whether the contact profile has been seen on your website. Using the identify method in the JS tracker.
customer_id:
type: string
description: The customer ID of this contact profile in your system.
firstname:
type: string
description: The first name of this contact profile.
middlename:
type: string
description: The middle name of this contact profile.
lastname:
type: string
description: The last name of this contact profile.
prefix:
type: string
description: The prefix of this contact profile.
suffix:
type: string
description: The suffix of this contact profile.
country:
type: string
description: The country of this contact profile. Following ISO 3166-1 alpha-2.
minLength: 2
maxLength: 2
country_id:
type: string
description: The country of this contact profile. Following ISO 3166-1 alpha-2.
minLength: 2
maxLength: 2
deprecated: true
gender:
type: string
description: The gender for this contact profile.
enum:
- m
- f
- o
tags:
type: array
description: Custom tags assigned to this profile in the Ometria UI.
items:
type: string
properties:
description: Custom key / value pairs of this contact profile.
type: object
date_of_birth:
type: string
description: The date of birth for this contact. Following ISO 8601 date format _YYYY-MM-DD_.
format: date
marketing_optin:
type: boolean
description: TRUE if this contact has explicitly opted in. FALSE if they have explicitly opted out. NULL otherwise.
timezone:
type: string
description: The timezone of the profile. Values defined in the <a href="https://www.iana.org/time-zones" target="blank">tz database</a>.
phone_number:
type: string
description: The contact's mobile phone number, in E.164/International format (e.g. starting "+447...")
phone_number_country:
type: string
description: The contact's mobile phone number country code, in ISO 3166-1 alpha-2 format (e.g. "GB")
stats:
$ref: '#/components/schemas/ProfileStats'
dates:
$ref: '#/components/schemas/ProfileDates'
lists:
$ref: '#/components/schemas/ProfileLists'
preferred_lang:
type: string
description: 'The preferred language of the contact.
This is supplied in ISO 639-1 format.'
identifiers:
type: array
description: All identifiers this profile resolves on, including standard identifiers (e.g. `email`, `customer_id`, `phone_number`) and any custom extra identifiers defined in your account's identity resolution configuration (e.g. `loyalty_id`). Each entry has a `type` (the identifier label) and a `value`. See <a href="https://support.ometria.com/hc/en-gb/articles/32595707442077-Custom-identifiers">Custom identifiers</a> for the full format, multi-valued identifiers, and CSV usage.
items:
$ref: '#/components/schemas/ProfileIdentifier'
example:
'@type': profile
id: 27f4-f0b281-00003039
email: bob22@example.com
name: smith111
country: null
seen: false
customer_id: '55555'
lastname: smith111
firstname: null
middlename: null
suffix: null
prefix: null
gender: m
tags:
- Attended VIP event 2017
properties:
custom_key: custom value
date_of_birth: '1984-04-22'
marketing_optin: null
stats:
orders: 1
orders_attempted: 1
total_items: 5
aov: 99.17
revenue: 99.17
visits: 20
dates:
first_seen: '2014-12-01T05:44:55+00:00'
last_seen: '2015-02-01T05:44:55+00:00'
first_purchase: '2015-02-01T05:44:55+00:00'
last_purchase: '2015-02-01T05:44:55+00:00'
predicted_next_purchase: '2015-03-01T05:44:55+00:00'
acquired: '2014-11-07T15:34:35+00:00'
account_created: '2014-11-07T15:34:35+00:00'
marketing_optin: '2014-11-09T15:34:35+00:00'
marketing_optout: null
preferred_lang: en-GB
identifiers:
- type: email
value: bob22@example.com
- type: customer_id
value: '55555'
- type: loyalty_id
value: LOY-55555
ProfileDates:
type: object
description: Contains date / time information of a profile
properties:
account_created:
type: string
description: The date time when this contact was created with given customer_id based on `timestamp_acquired` of the same listing.
format: date-time
acquired:
type: string
description: The date time when this contact was acquired based on the earliest `timestamp_acquired`.
format: date-time
first_seen:
type: string
description: The date time when this contact was first seen.
format: date-time
last_seen:
type: string
description: The date time when this contact was last seen.
format: date-time
first_purchase:
type: string
description: The date time when this contact first placed an order.
format: date-time
last_purchase:
type: string
description: The date time when this contact last placed an order.
format: date-time
predicted_next_purchase:
type: string
description: The date time of the projected next purchase based on the profile's average order gap.
format: date-time
marketing_optin:
type: string
description: The date time when this contact opted in to receive marketing emails.
format: date-time
marketing_optout:
type: string
description: The date time when this contact opted out to no longer receive marketing emails.
format: date-time
example:
first_seen: '2014-12-01T05:44:55+00:00'
last_seen: '2015-02-01T05:44:55+00:00'
first_purchase: '2015-02-01T05:44:55+00:00'
last_purchase: '2015-02-01T05:44:55+00:00'
predicted_next_purchase: '2015-03-01T05:44:55+00:00'
acquired: '2014-11-07T15:34:35+00:00'
account_created: '2014-11-07T15:34:35+00:00'
marketing_optin: '2014-11-09T15:34:35+00:00'
marketing_optout: null
ProfileLists:
type: array
description: Contains the saved segments (lists) that a profile belongs to.
items:
type: object
properties:
id:
type: string
description: The ID of the list
title:
type: string
description: The title of the list
type:
type: string
enum:
- STATIC
- DYNAMIC
example:
- id: 123
title: Title of the list
type: STATIC
ProfileIdentifier:
type: object
properties:
type:
type: string
description: Type of profile identifier. Any identifier defined in your account's identity resolution configuration is accepted (e.g. `customer_id`, `profile_hash`, `email_address`, `phone_number`, or any custom extra identifier such as `loyalty_id`).
value:
type: string
description: Value of profile identifier.
ErrorMessage:
type: object
properties:
status:
type: string
type:
type: string
detail:
type: string
title:
type: string
securitySchemes:
apikey:
type: apiKey
name: X-Ometria-Auth
in: header
description: Ometria API key which can be obtained from your Ometria account administrator
apiKeyReadTranslations:
type: apiKey
name: X-Ometria-Auth
in: header
description: 'Ometria API key which can be obtained from your Ometria account administrator. **Note**: The API key must have the scope `read:translations`.'
apiKeyWriteTranslations:
type: apiKey
name: X-Ometria-Auth
in: header
description: 'Ometria API key which can be obtained from your Ometria account administrator. **Note**: The API key must have the scope `write:translations`.'
x-explorer-enabled: false
x-readme:
proxy-enabled: true
samples-enabled: true