Custom Event

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ometria/json-schema/ometria-custom-event-schema.json",
  "title": "Custom Event",
  "description": "Describes a custom event. One of \"profile_id\", \"identity_email\", \"identity_account_id\" or \"extra_identifiers\" is required.",
  "x-generated": "2026-10-28",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/ometria-swagger-openapi.json#/components/schemas/CustomEvent",
  "type": "object",
  "required": [
    "@type",
    "id",
    "event_type",
    "timestamp",
    "properties"
  ],
  "properties": {
    "@type": {
      "type": "string",
      "description": "The value must be \"custom_event\". This shows that this record represents a <a href=\"https://support.ometria.com/hc/en-gb/articles/360011171077-Custom-events\" target=\"_blank\">custom_event</a> object."
    },
    "id": {
      "type": "string",
      "description": "The custom event ID, max length: 32.\nIf you exceed the character limit the field will pass validation but appear truncated in Ometria."
    },
    "event_type": {
      "type": "string",
      "description": "The <a href=\"https://support.ometria.com/hc/en-gb/articles/360011171077-Custom-events\" target=\"_blank\">custom_event</a> type, maximum characters 64.\nIf you exceed the character limit the field will pass validation but appear truncated in Ometria."
    },
    "timestamp": {
      "type": "string",
      "description": "The date and time of the event, following ISO 8601 DateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z."
    },
    "properties": {
      "$ref": "#/$defs/CustomEventProperties"
    },
    "profile_id": {
      "type": "string",
      "description": "The profile ID of the contact on which to trigger this custom event."
    },
    "identity_email": {
      "type": "string",
      "description": "The email of the contact record on which to trigger this custom event, max length: 255, lower case.\nIf left empty this field will be set to 'null'."
    },
    "identity_phone_number": {
      "type": "string",
      "description": "The phone_number of the contact record on which to trigger this custom event, in E.164/International format (e.g. starting \"+447...\").\nIf left empty this field will be set to 'null'."
    },
    "identity_account_id": {
      "type": "string",
      "description": "The <a href=\"https://ometria-api-reference.readme.io/docs/contacts-endpoint#customer-ids\" target=\"blank\">contact ID</a> of the contact record on which to trigger this custom event."
    },
    "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": {
    "CustomEventProperties": {
      "type": "object",
      "description": "These are the <a href=\"https://https://support.ometria.com/hc/en-gb/articles/360019668718\" target=\"_blank\">custom fields</a> you need to add for your custom event. There are 5 types available for custom event fields: string, boolean, number, products list and date.",
      "properties": {
        "string_custom_field": {
          "type": "string",
          "description": "Any characters permitted, including accents and other character symbols.\nString fields have a 512 character limit."
        },
        "boolean_custom_field": {
          "type": "boolean",
          "description": "`true` or `false`"
        },
        "number_custom_field": {
          "type": "number",
          "description": "Whole or decimal numbers"
        },
        "products_list_custom_field": {
          "type": "array",
          "description": "Returns a list of your <a href=\"https://support.ometria.com/hc/en-gb/articles/360011308998\" target=\"_blank\">products</a>",
          "items": {
            "type": "string"
          }
        },
        "date_custom_field": {
          "type": "string",
          "description": "Date and time, e.g. 2018-01-05 15:03:04",
          "format": "date"
        }
      }
    },
    "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)."
        }
      }
    }
  }
}