Profile

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ometria/json-schema/ometria-profile-schema.json",
  "title": "Profile",
  "description": "Describes an Ometria contact profile.",
  "x-generated": "2026-10-28",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/ometria-swagger-openapi.json#/components/schemas/Profile",
  "type": "object",
  "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": "#/$defs/ProfileStats"
    },
    "dates": {
      "$ref": "#/$defs/ProfileDates"
    },
    "lists": {
      "$ref": "#/$defs/ProfileLists"
    },
    "preferred_lang": {
      "type": "string",
      "description": "The preferred language of the contact.\nThis 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": "#/$defs/ProfileIdentifier"
      }
    }
  },
  "$defs": {
    "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"
        }
      }
    },
    "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."
        }
      }
    },
    "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"
            ]
          }
        }
      }
    },
    "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."
        }
      }
    }
  }
}