Create Or Update Custom Events

The following custom event types are supported by the Intelligems Custom Events API:

• clickEvent — Fires when a visitor clicks an element matching one or more CSS selectors

• scrollDepth — Fires when a visitor scrolls past a configured percentage of the page (separate thresholds for mobile and desktop)

• pageView — Fires when a visitor views a page matching applyToUrls

• productPageView — Fires when a visitor views one of a specific set of product pages

• collectionPageView — Fires when a visitor views one of a specific set of collection pages

• elementViewed — Fires when an element matching one or more CSS selectors enters the viewport

• javascriptEvent — Fires from a custom JavaScript snippet

Each type has its own settings shape — see the request schema for the full set of fields per type.

put

Creates a new custom event, or updates an existing one by passing back its id. customEvent accepts either a single event object, or an array of event objects (up to 50) to create/update several in one request.

Custom events let you define client-side behaviors (clicks, scroll depth, page views, etc.) that can be tracked as goals or triggers on experiences.

This is a full PUT replacement — when updating an existing event, the entire event configuration is replaced with the provided data. Any optional fields omitted from the request are reset to their defaults, not preserved from the previous version.

Required Fields (inside each event object)

• type - The kind of custom event (see supported types above)

• name - A name for the custom event

• settings - Type-specific configuration (e.g. CSS selectors for clickEvent, scroll percentages for scrollDepth)

• applyToUrls - Required only for pageView (at least one rule); has no effect and is ignored for productPageView/collectionPageView

Optional Fields (inside each event object)

• id (UUID) - Pass back the id from a previous create/update response to update that event in place instead of creating a new one. Omit to create a new event. Supplying an id that doesn't belong to your organization creates a new event rather than adopting or overwriting it.

• description (string) - Description of the custom event

Important Notes

• customEvent must be either a single event object or an array of up to 50 event objects — not a mix of anything else.

• identifier is server-generated and read-only; it is not guaranteed to stay the same across updates to the same event. Use id as the stable reference for an event, not identifier.

• Returns a 403 if your organization's plan does not include custom events tracking. This applies to both creating a new event and updating an existing one.

Authorizations

intelligems-access-tokenstringRequired

Intelligems external API access token.

Body

customEventany ofRequired

objectOptional

or

or

or

or

or

or

or

object[] · max: 50Optional

or

or

or

or

or

or

Responses

200

OK

application/json

put/v25-10-beta/custom-events

curl --location 'https://api.intelligems.io/v25-10-beta/custom-events' \
--header 'content-type: application/json' \
--header 'intelligems-access-token: YOUR_API_KEY' \
--data '{
  "customEvent": {
    "type": "clickEvent",
    "name": "Add to Cart Button Click",
    "settings": {
      "selectors": [".add-to-cart-button"]
    }
  }
}'

200

OK

{
  "customEvent": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "identifier": "text",
    "name": "text",
    "description": "text",
    "eventCountLastDay": 1,
    "lastEventTs": 1,
    "error": "text",
    "createdAtTs": 1,
    "lastUpdateTs": 1,
    "archivedAtTs": 1,
    "applyToUrls": [
      {
        "matchBy": "equals",
        "value": "text",
        "error": "text"
      }
    ],
    "experiencesList": [
      "text"
    ],
    "type": "text",
    "settings": {}
  }
}