---
updatedAt: 2026-05-22T15:57:54.000Z
agentTools:
projectIndex: https://docs.ometria.com/llms.txt
---
# Get Contact listing
Return a single Contact record
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"version": "1.1.0",
"title": "Ometria data API",
"description": "Welcome to the Ometria API reference.\n\n\nThe Ometria API is organized around the [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) 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.\n\n### HTTPS\n\nAll 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.\n\n### Message encoding\n\nThe V2 Ometria API uses JSON encoding for all data exchanges and assumes UTF-8 character encoding throughout.\n\n### Rate limits\n\nThe 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.\n\nIn 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"
}
},
"x-explorer-enabled": false,
"paths": {
"/contacts/{collection}/{contact_id}": {
"get": {
"tags": [
"Contacts"
],
"summary": "Get Contact listing",
"description": "Return a single Contact record",
"parameters": [
{
"name": "collection",
"in": "path",
"description": "The ID of the collection to which the contact belongs. The collection acts as a source for the record.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "contact_id",
"in": "path",
"description": "The ID of the contact to fetch.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Returns a contact record",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Contact"
}
}
}
},
"403": {
"description": "API key is not authorised to access this resource"
},
"404": {
"description": "Record with this ID does not exist"
}
}
}
}
},
"security": [
{
"apikey": []
}
],
"servers": [
{
"url": "https://api.ometria.com/v2"
}
],
"components": {
"securitySchemes": {
"apikey": {
"type": "apiKey",
"name": "X-Ometria-Auth",
"in": "header",
"description": "Ometria API key which can be obtained from your Ometria account administrator"
}
},
"schemas": {
"ExtraIdentifier": {
"title": "Extra Identifier",
"type": "object",
"description": "An additional identifier for a record, used to attach non-standard customer or record IDs (e.g. loyalty programme IDs, external CRM IDs). Records may carry multiple extra identifiers.",
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"description": "The identifier type label. Must contain only lowercase letters and underscores (regex `^[a-z_]+$`), 1-255 characters. Will be coerced to lowercase on ingestion.",
"minLength": 1,
"maxLength": 255,
"pattern": "^[a-z_]+$",
"example": "loyalty_id"
},
"value": {
"type": "string",
"description": "The identifier value (free-form string).",
"example": "LOY-7898734"
}
},
"example": {
"type": "loyalty_id",
"value": "LOY-7898734"
}
},
"Contact": {
"title": "Contact",
"type": "object",
"description": "Describes an individual Contact listing record. At least one of the following are required to identify the customer: `email`, `customer_id`, `phone_number`, or `extra_identifiers` (any one entry satisfies the requirement). Ometria attempts to merge each contact record into a single profile using the identifiers configured for your account; by default these are `customer_id` and then `email`. Accounts using identity resolution can configure additional identifiers and control how they are matched and merged.",
"required": [
"@type",
"id"
],
"properties": {
"@type": {
"type": "string",
"description": "The value must be \"contact\". This shows that this record represents a contact object."
},
"@collection": {
"type": "string",
"description": "The collection you want the contact to belong to."
},
"id": {
"type": "string",
"description": "The ID of this listing within the collection, max length: 255"
},
"email": {
"type": "string",
"description": "The contact's email address, max length: 255, lower case.\nIf left empty this field will be set to 'null'.\nYou must include either `email` or `customer_id` in every record. Some retailers can also use the `phone_number` or `extra_identifiers` field - speak to your Customer Success Representative if you're unsure."
},
"phone_number": {
"type": "string",
"description": "The contact's mobile phone number, in E.164/International format (e.g. starting \"+447...\") or National format (without the country code prefix, please note that country_id is required in order to validate the phone number in this format).\nYou must include either `email` or `customer_id` in every record. Some retailers can also use the `phone_number` or `extra_identifiers` field - speak to your Customer Success Representative if you're unsure."
},
"marketing_optin": {
"type": "string",
"description": "The contact's marketing opt-in status.",
"enum": [
"EXPLICITLY_OPTEDOUT",
"NOT_SPECIFIED",
"EXPLICITLY_OPTEDIN"
]
},
"customer_id": {
"type": "string",
"description": "Your universal customer ID for this contact, if applicable. max length: 255.\nOnly use this value if the customer ID is persistent across all your systems (that send data to Ometria).\nYou must include either `email` or `customer_id` in every record. Some retailers can also use the `phone_number` or `extra_identifiers` field - speak to your Customer Success Representative if you're unsure."
},
"@add_to_lists": {
"type": "array",
"description": "The ID of the segment you want to send this contact to, max length: 16.",
"items": {
"type": "integer"
}
},
"@remove_from_lists": {
"type": "array",
"description": "The ID of the segment you want to remove this contact from, max length: 16.",
"items": {
"type": "integer"
}
},
"@force_optin": {
"type": "boolean",
"description": "If 'True', this field overrides marketing opt-in priority."
},
"@merge": {
"type": "boolean",
"description": "If 'True', this call will not override blank fields (i.e. fields that exist but aren't passed)"
},
"prefix": {
"type": "string",
"description": "The contact's title.\nOmetria accepts any of the following: Mr, Mrs, Miss, Ms.\nIf the gender field is left empty, Ometria infers gender from the prefix (e.g. Mr will be 'm', Ms will be 'f', etc.)\nmax length: 16."
},
"firstname": {
"type": "string",
"description": "The contact's first name, max length: 64."
},
"middlename": {
"type": "string",
"description": "The contact's middle name, max length: 64."
},
"lastname": {
"type": "string",
"description": "The contact's last name, max length: 64."
},
"gender": {
"type": "string",
"description": "The contact's gender.\nWe currently support the values \"m\" (man), \"f\" (woman) and \"o\" (other).\nUse the value \"o\" when the contact's gender is known but it is not \"m\" or \"f\". If the contact's gender is unknown then the field \"gender\" should not be included.\nIf left empty, gender is inferred from the contact's prefix (e.g 'Ms' will be 'f').",
"enum": [
"m",
"f",
"o"
]
},
"date_of_birth": {
"type": "string",
"description": "The contact's date of birth.\nFollowing ISO 8601 date format YYYY-MM-DD.",
"format": "date"
},
"postcode": {
"type": "string",
"description": "The contact's postalcode"
},
"city": {
"type": "string",
"description": "The contact's city"
},
"country_id": {
"type": "string",
"description": "The contact's country, must be 2 characters, upper case, e.g. 'GB'.\nFollow ISO 3166-1 alpha-2.\nIf you exceed the character limit this field will pass validation but appear truncated in Ometria.\nIf left empty this field will be set to 'null'.",
"minLength": 2,
"maxLength": 2
},
"store_ids": {
"type": "array",
"description": "An array of strings for which stores the customer belongs to.\nmax length: 31, lower case.\nIf left empty this field will be set to 'null'.",
"items": {
"type": "string"
}
},
"timezone": {
"type": "string",
"description": "As defined in the tz database, max length: 64."
},
"properties": {
"type": "object",
"description": "Custom key value pairs"
},
"timestamp_acquired": {
"type": "string",
"description": "The date and time the contact was 'acquired'. Only provide this if known.\nFollow ISO 8601 DateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z",
"format": "date-time"
},
"timestamp_subscribed": {
"type": "string",
"description": "The date and time the contact was 'subscribed'. Only provide this if known.\nFollow ISO 8601 DateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z",
"format": "date-time"
},
"timestamp_unsubscribed": {
"type": "string",
"description": "The date and time the contact was 'unsubscribed'. Only provide if known.\nFollow ISO 8601 DateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z",
"format": "date-time"
},
"channels": {
"type": "object",
"description": "Contact preferences across different communication channels, e.g. SMS",
"properties": {
"sms": {
"type": "object",
"description": "SMS channel opt-in preferences.",
"properties": {
"allow_marketing": {
"type": "boolean",
"description": "Whether the contact is opted in/out for SMS marketing. If left out, this implies unspecified."
},
"allow_transactional": {
"type": "boolean",
"description": "Whether the contact is opted in/out to transactional SMS. If left out, it implies 'unspecified'."
},
"dt_updated_marketing": {
"type": "string",
"format": "date-time",
"description": "The date and time the contact updated their marketing SMS preference.\nOnlyprovide if known.\nFollow ISO 8601 DateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z"
},
"dt_updated_transactional": {
"type": "string",
"format": "date-time",
"description": "The date and time the contact updated their transactional SMS preference. Only\nprovide if known.\nFollow ISO 8601 DateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z"
}
}
}
}
},
"subscriptions": {
"type": "object",
"description": "Marketing opt-in preferences for additional channels, e.g. direct mail. Each key is a channel name and its value describes the contact's preference for that channel.",
"properties": {
"direct_mail": {
"type": "object",
"description": "Direct mail (postal) marketing opt-in preference.",
"properties": {
"allow_marketing": {
"type": "boolean",
"description": "Whether the contact is opted in/out for direct mail marketing. If left out, this implies unspecified."
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "The date and time the contact updated their direct mail marketing preference. Only provide if known.\nFollow ISO 8601 DateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z"
},
"value": {
"type": "string",
"description": "The contact's postal address, supplied as a JSON-encoded string. Supported fields: \"address_line_1\", \"city\", \"state\", \"postcode\", \"country_code\" (2 characters, upper case, following ISO 3166-1 alpha-2) and \"address_type\" (e.g. \"shipping\")."
}
}
}
}
},
"preferred_lang": {
"type": "string",
"description": "The preferred language of the contact.\nThis should be supplied in ISO 639-1 format."
},
"extra_identifiers": {
"type": "array",
"description": "Optional list of extra identifiers (such as a loyalty ID) as per your identity resolution configuration, e.g. `loyalty_id`. Custom identifiers must be configured for your account before you send them. See Custom identifiers for the full format, multi-valued identifiers, and CSV usage.",
"nullable": true,
"items": {
"$ref": "#/components/schemas/ExtraIdentifier"
}
}
},
"example": {
"@type": "contact",
"@collection": "default",
"id": "123",
"email": "john.smith@example.com",
"phone_number": "+447812123456",
"store_ids": [
"gb"
],
"customer_id": "7898734",
"prefix": "Mr",
"firstname": "John",
"middlename": "Fredrick",
"lastname": "Smith",
"gender": "m",
"date_of_birth": "1985-01-05",
"marketing_optin": "EXPLICITLY_OPTEDIN",
"postcode": "SW1A 1AA",
"city": "London",
"country_id": "GB",
"properties": {
"nickname": "Johnny",
"number_of_cats": 4
},
"timestamp_subscribed": "2015-01-02T09:00:00+00",
"@add_to_lists": [
1,
2,
3
],
"@remove_from_lists": [
4,
5,
6
],
"channels": {
"sms": {
"allow_marketing": true,
"allow_transactional": true,
"dt_updated_marketing": "2015-01-02T09:00:00+00",
"dt_updated_transactional": "2015-01-02T09:00:00+00"
}
},
"subscriptions": {
"direct_mail": {
"allow_marketing": true,
"timestamp": "2015-01-02T09:00:00+00",
"value": "{\"address_line_1\": \"63 Laurelbank Cres\", \"city\": \"Keswick\", \"state\": \"ON\", \"postcode\": \"L4P 4H7\", \"country_code\": \"CA\", \"address_type\": \"shipping\"}"
}
},
"preferred_lang": "en-GB",
"extra_identifiers": [
{
"type": "loyalty_id",
"value": "LOY-7898734"
},
{
"type": "external_id",
"value": "crm-abc-123"
}
]
}
}
}
},
"x-readme": {
"proxy-enabled": true,
"samples-enabled": true
}
}
```