Contact

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ometria/json-schema/ometria-contact-schema.json",
  "title": "Contact",
  "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.",
  "x-generated": "2026-10-28",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/ometria-swagger-openapi.json#/components/schemas/Contact",
  "type": "object",
  "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 <a href=\"https://ometria-api-reference.readme.io/docs/contacts-endpoint#marketing-opt-in-rules-of-priority\" target=\"_blank\">marketing opt-in priority</a>."
    },
    "@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 <a href=\"https://www.iana.org/time-zones\" target=\"blank\">tz database</a>, 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",
        "null"
      ],
      "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 <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": "#/$defs/ExtraIdentifier"
      }
    }
  },
  "$defs": {
    "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_]+$"
        },
        "value": {
          "type": "string",
          "description": "The identifier value (free-form string)."
        }
      }
    }
  }
}