Menu
OneTrace.pro

API reference

Event collection, profiles, segments, journeys and campaigns — an OpenAPI 3.1 specification.

Overview

Public API v1: event ingestion (write keys) and project management (secret keys with permissions). Errors are {"message": "..."}; validation errors add errors by field path. Lists use cursor pagination (limit 1-200, cursor from next_cursor). POST requests accept an Idempotency-Key header: a repeat with the same key and body returns the stored response for 24 hours. Rate limits: 6000 requests/min per write key, 1200 requests/min per secret key (429). Error messages follow Accept-Language (en, ru, de, es, fr, it, pt, tr, uz, zh), otherwise the platform default language.

Base URL: https://cdp.onetrace.pro/api/v1

Keys

  • writeKeyhttp bearer
    cdp_wk_…: ingestion only. Also accepted as Basic auth user or writeKey body field.
  • secretKeyhttp bearer
    cdp_sk_…: server-side only, permissions chosen when the key is created.

Ingest

Track an event

post/track

Key: writeKey or secretKey

Request bodyrequired

Message

  • typestring

    values: "track", "identify", "page", "screen", "alias"

  • messageIdstring

    length: ≤ 100

  • anonymousIdstring | integer
  • userIdstring | integer
  • userHashstring
    Signature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.

    length: ≤ 128

  • previousIdstring | integer
  • eventstring

    length: ≤ 200

  • namestring
  • propertiesobject
  • traitsobject
  • contextobject
  • consentsobject[]
    identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.

    items: ≤ 20

    • channelstringrequired

      pattern: ^[a-z0-9_]{1,64}$ · example: "email"

    • topicstring
      Subscription topic; the whole channel if omitted.

      pattern: ^[a-z0-9_-]{1,64}$

    • statusstringrequired

      values: "subscribed", "unsubscribed"

  • timestampstring (date-time)
Request body example
{
  "type": "track",
  "messageId": "string",
  "anonymousId": "string",
  "userId": "string",
  "userHash": "string",
  "previousId": "string",
  "event": "string",
  "name": "string",
  "properties": {},
  "traits": {},
  "context": {},
  "consents": [
    {
      "channel": "email",
      "topic": "string",
      "status": "subscribed"
    }
  ],
  "timestamp": "2026-01-01T10:00:00Z"
}

Responses

  • 202Accepted for asynchronous processing
    • acceptedinteger
    • duplicatesinteger
  • 401Missing, invalid or revoked key · Error
  • 413Body over 1 MB · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Identify a profile and update traits

post/identify

Key: writeKey or secretKey

Request bodyrequired

Message

  • typestring

    values: "track", "identify", "page", "screen", "alias"

  • messageIdstring

    length: ≤ 100

  • anonymousIdstring | integer
  • userIdstring | integer
  • userHashstring
    Signature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.

    length: ≤ 128

  • previousIdstring | integer
  • eventstring

    length: ≤ 200

  • namestring
  • propertiesobject
  • traitsobject
  • contextobject
  • consentsobject[]
    identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.

    items: ≤ 20

    • channelstringrequired

      pattern: ^[a-z0-9_]{1,64}$ · example: "email"

    • topicstring
      Subscription topic; the whole channel if omitted.

      pattern: ^[a-z0-9_-]{1,64}$

    • statusstringrequired

      values: "subscribed", "unsubscribed"

  • timestampstring (date-time)
Request body example
{
  "type": "track",
  "messageId": "string",
  "anonymousId": "string",
  "userId": "string",
  "userHash": "string",
  "previousId": "string",
  "event": "string",
  "name": "string",
  "properties": {},
  "traits": {},
  "context": {},
  "consents": [
    {
      "channel": "email",
      "topic": "string",
      "status": "subscribed"
    }
  ],
  "timestamp": "2026-01-01T10:00:00Z"
}

Responses

  • 202Accepted for asynchronous processing
    • acceptedinteger
    • duplicatesinteger
  • 401Missing, invalid or revoked key · Error
  • 413Body over 1 MB · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Track a page view

post/page

Key: writeKey or secretKey

Request bodyrequired

Message

  • typestring

    values: "track", "identify", "page", "screen", "alias"

  • messageIdstring

    length: ≤ 100

  • anonymousIdstring | integer
  • userIdstring | integer
  • userHashstring
    Signature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.

    length: ≤ 128

  • previousIdstring | integer
  • eventstring

    length: ≤ 200

  • namestring
  • propertiesobject
  • traitsobject
  • contextobject
  • consentsobject[]
    identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.

    items: ≤ 20

    • channelstringrequired

      pattern: ^[a-z0-9_]{1,64}$ · example: "email"

    • topicstring
      Subscription topic; the whole channel if omitted.

      pattern: ^[a-z0-9_-]{1,64}$

    • statusstringrequired

      values: "subscribed", "unsubscribed"

  • timestampstring (date-time)
Request body example
{
  "type": "track",
  "messageId": "string",
  "anonymousId": "string",
  "userId": "string",
  "userHash": "string",
  "previousId": "string",
  "event": "string",
  "name": "string",
  "properties": {},
  "traits": {},
  "context": {},
  "consents": [
    {
      "channel": "email",
      "topic": "string",
      "status": "subscribed"
    }
  ],
  "timestamp": "2026-01-01T10:00:00Z"
}

Responses

  • 202Accepted for asynchronous processing
    • acceptedinteger
    • duplicatesinteger
  • 401Missing, invalid or revoked key · Error
  • 413Body over 1 MB · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Track a mobile app screen view (event $screen, the screen name in properties.name)

post/screen

Key: writeKey or secretKey

Request bodyrequired

Message

  • typestring

    values: "track", "identify", "page", "screen", "alias"

  • messageIdstring

    length: ≤ 100

  • anonymousIdstring | integer
  • userIdstring | integer
  • userHashstring
    Signature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.

    length: ≤ 128

  • previousIdstring | integer
  • eventstring

    length: ≤ 200

  • namestring
  • propertiesobject
  • traitsobject
  • contextobject
  • consentsobject[]
    identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.

    items: ≤ 20

    • channelstringrequired

      pattern: ^[a-z0-9_]{1,64}$ · example: "email"

    • topicstring
      Subscription topic; the whole channel if omitted.

      pattern: ^[a-z0-9_-]{1,64}$

    • statusstringrequired

      values: "subscribed", "unsubscribed"

  • timestampstring (date-time)
Request body example
{
  "type": "track",
  "messageId": "string",
  "anonymousId": "string",
  "userId": "string",
  "userHash": "string",
  "previousId": "string",
  "event": "string",
  "name": "string",
  "properties": {},
  "traits": {},
  "context": {},
  "consents": [
    {
      "channel": "email",
      "topic": "string",
      "status": "subscribed"
    }
  ],
  "timestamp": "2026-01-01T10:00:00Z"
}

Responses

  • 202Accepted for asynchronous processing
    • acceptedinteger
    • duplicatesinteger
  • 401Missing, invalid or revoked key · Error
  • 413Body over 1 MB · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Link a previous identifier to a user

post/alias

Key: writeKey or secretKey

Request bodyrequired

Message

  • typestring

    values: "track", "identify", "page", "screen", "alias"

  • messageIdstring

    length: ≤ 100

  • anonymousIdstring | integer
  • userIdstring | integer
  • userHashstring
    Signature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.

    length: ≤ 128

  • previousIdstring | integer
  • eventstring

    length: ≤ 200

  • namestring
  • propertiesobject
  • traitsobject
  • contextobject
  • consentsobject[]
    identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.

    items: ≤ 20

    • channelstringrequired

      pattern: ^[a-z0-9_]{1,64}$ · example: "email"

    • topicstring
      Subscription topic; the whole channel if omitted.

      pattern: ^[a-z0-9_-]{1,64}$

    • statusstringrequired

      values: "subscribed", "unsubscribed"

  • timestampstring (date-time)
Request body example
{
  "type": "track",
  "messageId": "string",
  "anonymousId": "string",
  "userId": "string",
  "userHash": "string",
  "previousId": "string",
  "event": "string",
  "name": "string",
  "properties": {},
  "traits": {},
  "context": {},
  "consents": [
    {
      "channel": "email",
      "topic": "string",
      "status": "subscribed"
    }
  ],
  "timestamp": "2026-01-01T10:00:00Z"
}

Responses

  • 202Accepted for asynchronous processing
    • acceptedinteger
    • duplicatesinteger
  • 401Missing, invalid or revoked key · Error
  • 413Body over 1 MB · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Send up to 500 messages at once

post/batch

Key: writeKey or secretKey

Request bodyrequired

Request body example
{
  "batch": [
    {
      "type": "track",
      "messageId": "string",
      "anonymousId": "string",
      "userId": "string",
      "userHash": "string",
      "previousId": "string",
      "event": "string",
      "name": "string",
      "properties": {},
      "traits": {},
      "context": {},
      "consents": [
        {
          "channel": "email",
          "topic": "string",
          "status": "subscribed"
        }
      ],
      "timestamp": "2026-01-01T10:00:00Z"
    }
  ]
}

Responses

  • 202Accepted for asynchronous processing
    • acceptedinteger
    • duplicatesinteger
  • 401Missing, invalid or revoked key · Error
  • 413Body over 1 MB · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Check the API key

get/key

Key type, project and permissions. Accepts any active key (write or secret); use it for a "Test connection" button.

Key: writeKey or secretKey

Responses

  • 200OK
    • typestringrequired

      values: "write", "secret"

    • namestringrequired
    • projectobjectrequired
      • uidstring
      • namestring
      • timezonestring
    • scopesstring[]required
      Permissions of a secret key; empty for a write key.
  • 401Missing, invalid or revoked key · Error
  • 429Rate limit or monthly event quota exceeded · Error

Tracker module settings in one request

get/site/config

For the website tracker (cdp.js 1.38.4+): settings of the chat, message feed, subscription forms, search layer and product question widget in one response — the same objects as GET /chat/config, /feed/config, /forms, /search/widget and /products/questions/widget, which stay for older trackers. A part that fails or is not available on the plan comes back disabled.

Key: writeKey

Parameters

  • languagequerystring
    Visitor language (BCP 47).

    length: ≤ 35

  • anonymousIdquerystring
    Visitor id: forms shown to segment members are filtered by the visitor's profile.

    length: ≤ 255

Responses

  • 200Settings
    • chatobject
      As GET /chat/config
    • feedobject
      As GET /feed/config
    • formsobject
      As GET /forms
    • searchobject
      As GET /search/widget; enabled: false without the product search feature
    • askobject
      As GET /products/questions/widget
  • 401Missing, invalid or revoked key · Error
  • 429Rate limit or monthly event quota exceeded · Error

Push

VAPID public key for PushManager.subscribe()

get/push/config

Key: writeKey or secretKey

Responses

  • 200Public key of the project's Web Push integration
    • public_keystringrequired
      base64url, 65-byte uncompressed P-256 point
  • 401Missing, invalid or revoked key · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Store a browser push subscription and link it to the visitor

post/push/subscriptions

Key: writeKey or secretKey

Request bodyrequired

  • anonymousIdstring
    Required without userId

    length: ≤ 255

  • userIdstring

    length: ≤ 255

  • userHashstring
    Signature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.

    length: ≤ 128

  • publicKeystring
    VAPID key the subscription was created with
  • subscriptionobjectrequired
    PushSubscription.toJSON(); the endpoint must belong to a browser push service
    • endpointstring (uri)required
    • expirationTimeinteger | null
    • keysobjectrequired
      • p256dhstringrequired
      • authstringrequired
Request body example
{
  "anonymousId": "string",
  "userId": "string",
  "userHash": "string",
  "publicKey": "string",
  "subscription": {
    "endpoint": "https://example.com",
    "expirationTime": 0,
    "keys": {
      "p256dh": "string",
      "auth": "string"
    }
  }
}

Responses

  • 201Subscription stored; consent is recorded once the profile is processed
    • subscription_idstring
  • 401Missing, invalid or revoked key · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Forget a browser push subscription

delete/push/subscriptions

Key: writeKey or secretKey

Request bodyrequired

  • endpointstringrequired
Request body example
{
  "endpoint": "string"
}

Responses

  • 200Whether a subscription was removed
    • deletedboolean
  • 401Missing, invalid or revoked key · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Register a mobile app installation from the SDK: push token, notification permission and device details

post/devices

Called by the mobile SDKs on launch, when the push token or the notification permission changes, and on identify and reset. While the installation has a token and notifications are allowed, the profile gets the mobile_push identity and consent to the mobile_push channel; otherwise the identity is removed. A token registered by another installation moves here.

Key: writeKey or secretKey

Request bodyrequired

  • installationIdstringrequired
    Random id the SDK generates once per installation

    pattern: ^[A-Za-z0-9_-]{8,64}$

  • anonymousIdstring
    Required without userId

    length: ≤ 255

  • userIdstring

    length: ≤ 255

  • userHashstring
    Signature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.

    length: ≤ 128

  • appobjectrequired
    • idstringrequired
      iOS bundle id or Android package name
    • versionstring
    • buildstring
  • osobjectrequired
    • namestringrequired

      values: "ios", "android"

    • versionstring
  • deviceobject
    • manufacturerstring
    • modelstring
  • localestring

    length: ≤ 35

  • timezonestring
    IANA time zone

    length: ≤ 64

  • pushobject
    • providerstring

      values: "fcm", "apns"

    • tokenstring

      length: ≤ 4096

    • enabledboolean
      Notifications are allowed by the user
  • sdkobject
    • namestring
    • versionstring
Request body example
{
  "installationId": "string",
  "anonymousId": "string",
  "userId": "string",
  "userHash": "string",
  "app": {
    "id": "string",
    "version": "string",
    "build": "string"
  },
  "os": {
    "name": "ios",
    "version": "string"
  },
  "device": {
    "manufacturer": "string",
    "model": "string"
  },
  "locale": "string",
  "timezone": "string",
  "push": {
    "provider": "fcm",
    "token": "string",
    "enabled": true
  },
  "sdk": {
    "name": "string",
    "version": "string"
  }
}

Responses

  • 200Installation stored
    • installation_idstring
    • pushboolean
      Push notifications can be sent to this installation
  • 401Missing, invalid or revoked key · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Report that a mobile push was received by the app or opened by a tap

post/push/events

The SDK sends the signed cdp_token from the notification data. opened with url records an open and a click on that link; received marks the message delivered. A token of another project or channel is ignored (recorded: false).

Key: writeKey or secretKey

Request bodyrequired

  • tokenstringrequired
    cdp_token from the notification data

    length: ≤ 100

  • eventstringrequired

    values: "received", "opened"

  • urlstring
    The link opened by the tap (cdp_url)

    length: ≤ 2000

Request body example
{
  "token": "string",
  "event": "received",
  "url": "string"
}

Responses

  • 200Processed
    • recordedboolean
  • 401Missing, invalid or revoked key · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

In-app messages waiting to be shown on this installation

get/in-app/messages

For the mobile SDKs. Messages of the profile of the anonymous id (a random id, never the guessable user id), oldest first, up to 10, only those of in-app integrations for this app. Empty without the in_app plan feature.

Key: writeKey or secretKey

Parameters

  • anonymousIdquerystringrequired

    length: ≤ 255

  • appIdquerystringrequired
    Bundle id or package name
  • platformquerystringrequired

    values: "ios", "android"

Responses

  • 200Messages
    • dataobject[]
      • tokenstring
        Pass it back to /in-app/events
      • trigger_eventstring | null
        Show after the app tracks this event; null — on the next app open
      • layoutstring

        values: "modal", "banner", "fullscreen"

      • positionstring

        values: "top", "bottom"

      • titlestring
      • bodystring
      • image_urlstring
      • button_textstring
      • button_urlstring
      • close_textstring
      • background_colorstring
      • text_colorstring
      • button_colorstring
      • button_text_colorstring
  • 401Missing, invalid or revoked key · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Report that an in-app message was shown, clicked or dismissed

post/in-app/events

shown marks the message delivered and opened and stops returning it; clicked with url records a click.

Key: writeKey or secretKey

Request bodyrequired

  • tokenstringrequired

    length: ≤ 100

  • eventstringrequired

    values: "shown", "clicked", "dismissed"

  • urlstring

    length: ≤ 2000

Request body example
{
  "token": "string",
  "event": "shown",
  "url": "string"
}

Responses

  • 200Processed
    • recordedboolean
  • 401Missing, invalid or revoked key · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Message feed of this visitor

get/feed

For the website tracker and the mobile SDKs. Cards of the profile of the anonymous id (a random id, never the guessable user id): pinned first, then newest, up to 50, without expired and dismissed ones; unread — cards not shown yet. Empty without the feed plan feature.

Key: writeKey or secretKey

Parameters

  • anonymousIdquerystringrequired

    length: ≤ 255

Responses

  • 200Feed
    • dataobject[]
      • tokenstring
        Pass it back to /feed/events
      • layoutstring
        classic — image on the left, captioned — image on top, banner — image only

        values: "classic", "captioned", "banner"

      • titlestring
      • bodystring
      • image_urlstring
      • button_textstring
        Absent — the whole card is the link
      • button_urlstring
      • pinnedboolean
      • readboolean
        Already shown in the feed
      • created_atstring (date-time)
      • expires_atstring (date-time)
    • unreadinteger
  • 401Missing, invalid or revoked key · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Website widget settings of the message feed

get/feed/config

For the website tracker: whether to show the feed and where — button (floating bell with a counter), element (an icon in every [data-cdp-feed] element) or chat (a tab in the chat window; becomes button while the chat is off). Disabled without the feed plan feature or a feed integration shown on the website.

Key: writeKey or secretKey

Responses

  • 200Settings
    • enabledboolean
    • placementstring

      values: "button", "element", "chat"

    • positionstring

      values: "right", "left"

    • colorstring
    • titlestring | null
      Null — the default title in the visitor's language
  • 401Missing, invalid or revoked key · Error
  • 429Rate limit or monthly event quota exceeded · Error

Report that a feed card was shown, clicked or dismissed

post/feed/events

shown marks the card read, the message delivered and opened (once); clicked with url records a click; dismissed removes the card from the feed.

Key: writeKey or secretKey

Request bodyrequired

  • tokenstringrequired

    length: ≤ 100

  • eventstringrequired

    values: "shown", "clicked", "dismissed"

  • urlstring

    length: ≤ 2000

Request body example
{
  "token": "string",
  "event": "shown",
  "url": "string"
}

Responses

  • 200Processed
    • recordedboolean
  • 401Missing, invalid or revoked key · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Recommendations

Product recommendations for the site

get/recommendations

Write key (tracker). Personal and recently viewed recommendations use the profile of anonymousId only. Only available products are returned. replenish — products the visitor buys regularly whose repeat-purchase cycle has come (needs “Time to reorder” in the recommendation settings).

Key: writeKey or secretKey

Parameters

  • typequerystringrequired

    values: "personal", "popular", "trending", "viewed_with", "bought_with", "similar", "recently_viewed", "replenish"

  • limitqueryinteger

    default: 8 · range: 1–24

  • itemquerystring
    Context product id (or item[] for a cart) for viewed_with, bought_with, similar.
  • categoryquerystring
    Category id for popular and trending.
  • exclude[]querystring[]
  • anonymousIdquerystring
  • image_widthqueryinteger
    Card image width (image), px. Variants for are in srcset when imgproxy is configured (ADR-047).

    default: 480 · range: 64–1200

  • languagequerystring
    Visitor language (BCP 47, as in context.locale): product names and links come in the catalog translation for the closest language (ADR-080).

    length: ≤ 35

Responses

  • 200Recommended products
  • 401Missing, invalid or revoked key · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Website widget configured in the admin panel

get/widgets/{uid}

Write key (tracker renders
, ADR-048). Returns the widget settings and its products in one request; a paused widget returns no items. Personal recommendations use the profile of anonymousId only. A widget outside its display rules returns no items and hidden: true; variant is the A/B variant of the visitor (null — no variants).

Key: writeKey or secretKey

Parameters

  • uidpathstringrequired

    pattern: ^[a-z0-9]{1,16}$

  • item[]querystring[]
    Context product ids (data-item): page product or cart items.
  • categoryquerystring
    Category id (data-category); overrides the widget category.
  • exclude[]querystring[]
  • anonymousIdquerystring
  • languagequerystring
    Visitor language (BCP 47, as in context.locale): the heading, the button and product names come in their translation for the closest language (ADR-078, ADR-080).

    length: ≤ 35

  • urlquerystring
    Page address without the domain (path and query): display rules by pages (ADR-139).

    length: ≤ 2000

  • devicequerystring
    Visitor device for the display rules (ADR-139).

    values: "desktop", "mobile"

  • visitorquerystring
    New (first session on the website) or returning visitor for the display rules (ADR-139).

    values: "new", "returning"

  • previewquerystring
    Signed preview mark from the admin panel (cdp_preview in the page address, valid for 24 hours): the saved widget is shown in the chosen variant even if paused or outside the display rules; the response has preview: true and no request_id, views and clicks are not tracked (ADR-139).

    length: ≤ 200

Responses

  • 200Widget and products
    • widgetobject
      • uidstring
      • typestring
      • statusstring

        values: "active", "paused"

      • settingsobject
        • titlestring
        • layoutstring

          values: "grid", "carousel"

        • columnsinteger
        • accentstring | null
        • radiusinteger
        • buttonstring
        • showPriceboolean
      • variantstring | null
      • previewboolean
    • request_idstring | null
    • hiddenboolean
  • 401Invalid key
  • 403Request origin is not one of the key website domains
  • 404Widget not found in the project

Personal block configured in the admin panel

get/blocks/{uid}

Write key (tracker renders
, ADR-170). Returns the content chosen for the visitor: the first segment row the profile of anonymousId belongs to (arm s1–s5), otherwise the default content or its A/B variant (arm a–d). A paused block or a block outside its display rules returns block: null and hidden: true. Requires the site_personalization plan feature (402 otherwise).

Key: writeKey or secretKey

Parameters

  • uidpathstringrequired

    pattern: ^[a-z0-9]{1,16}$

  • anonymousIdquerystring
  • languagequerystring
    Visitor language (BCP 47, as in context.locale): the banner texts and the HTML come in their translation for the closest language.

    length: ≤ 35

  • urlquerystring
    Page address without the domain (path and query): display rules by pages.

    length: ≤ 2000

  • devicequerystring
    Visitor device for the display rules.

    values: "desktop", "mobile"

  • visitorquerystring
    New (first session on the website) or returning visitor for the display rules.

    values: "new", "returning"

  • previewquerystring
    Signed preview mark from the admin panel (cdp_preview in the page address, valid for 24 hours): the saved block is shown in the chosen arm even if paused or outside the display rules; the response has preview: true, views and clicks are not tracked.

    length: ≤ 200

Responses

  • 200Block content
    • blockobject | null
      • uidstring
      • armstring
        a–d: default content and its variants; s1–s5: segment rows
      • contentobject
        Banner (type: banner: layout, title, text, button_text, button_url, image_url, colours, radius) or sanitized HTML (type: html: html) and custom CSS for the shadow root.
      • previewboolean
    • hiddenboolean
  • 401Missing, invalid or revoked key · Error
  • 402The plan has no `site_personalization` feature
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Meta

This OpenAPI specification

get/openapi.json

Key: not needed

Responses

  • 200OK

    object

Profiles

Get a profile by any identifier

get/profiles/{type}/{value}

Traits and identifiers are masked unless the key has profiles.pii.

Key: secretKey · Permissions: profiles.read

Parameters

  • typepathstringrequired

    values: "user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"

  • valuepathstringrequired
    Normalized like at ingestion (lower-case email, E.164 phone).

Responses

  • 200OK

    Profile

    • idinteger
    • traitsobject
    • identitiesobject
    • first_seen_atstring (date-time)
    • last_seen_atstring (date-time)
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Erase a profile and all profiles merged into it (GDPR)

delete/profiles/{type}/{value}

Key: secretKey · Permissions: profiles.delete

Parameters

  • typepathstringrequired

    values: "user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"

  • valuepathstringrequired
    Normalized like at ingestion (lower-case email, E.164 phone).

Responses

  • 204Erased
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Profile events, newest first, 50 per page

get/profiles/{type}/{value}/events

Key: secretKey · Permissions: profiles.read

Parameters

  • typepathstringrequired

    values: "user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"

  • valuepathstringrequired
    Normalized like at ingestion (lower-case email, E.164 phone).
  • beforequerystring (date-time)
    Cursor: next_before of the previous page.
  • namequerystring

Responses

  • 200OK
    • next_beforestring (date-time) | null
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Subscribe or unsubscribe a profile

put/profiles/{type}/{value}/consents

Key: secretKey · Permissions: profiles.write

Parameters

  • typepathstringrequired

    values: "user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"

  • valuepathstringrequired
    Normalized like at ingestion (lower-case email, E.164 phone).

Request bodyrequired

  • channelstringrequired
    Channel key, or ads for the advertising consent: whether the profile's data may be sent to ad platforms (conversions, audiences); ads always applies to the whole channel.

    example: "email"

  • topicstring
    Omit for the whole channel (all).
  • statusstringrequired

    values: "subscribed", "unsubscribed"

Request body example
{
  "channel": "email",
  "topic": "string",
  "status": "subscribed"
}

Responses

  • 200OK

    object

  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Subscription preferences of a profile

get/profiles/{type}/{value}/preferences

Topics by channel, frequency and pause of marketing messages, and a signed link to the preference center page.

Key: secretKey · Permissions: profiles.read

Parameters

  • typepathstringrequired

    values: "user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"

  • valuepathstringrequired
    Normalized like at ingestion (lower-case email, E.164 phone).
  • languagequerystring
    Language of topic names; the project default when omitted.

Responses

  • 200OK

    ProfilePreferences

    • profile_idinteger
    • languagestring
      Language of topic names.

      example: "en"

    • channelsobject[]
      Channels the profile receives or can receive messages in: channels of its consents and messages of the last year, and channels of active integrations it has an address for.
      • keystring

        example: "email"

      • namestring
        Name of the channel in the requested language, lower case as inside a sentence.

        example: "email"

      • blockedboolean
        Hard block (the address does not exist, the bot was stopped): read only.
    • unsubscribed_allboolean
      The profile unsubscribed from marketing messages in all channels (unsubscribe_all or the preference center): channels without their own subscription stay closed.
    • adsboolean | null
      Advertising consent; null — the project has no ad platform connected, nothing to ask.
    • topicsobject[]
      Visible subscription topics.
      • keystring

        example: "news"

      • namestring
      • descriptionstring
      • channelsobject
        Channel key → subscribed (true/false), null — the topic is not offered in this channel.
    • frequencystring | null
      At most one marketing message per week or month across channels; null — as usual.

      values: "weekly", "monthly", null

    • paused_untilstring (date-time) | null
      Marketing messages are paused until this time.
    • preferences_urlstring (uri)
      Signed link to the preference center page of this profile, valid for 30 days — for a «Manage subscriptions» link in the store account.
    • preferences_url_expires_atstring (date-time)
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Change subscription preferences of a profile

put/profiles/{type}/{value}/preferences

Key: secretKey · Permissions: profiles.write

Parameters

  • typepathstringrequired

    values: "user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"

  • valuepathstringrequired
    Normalized like at ingestion (lower-case email, E.164 phone).

Request bodyrequired

  • topicsobject
    Topic key → channel key → subscribed. Only the given topics and channels change.

    example: {"news":{"email":true},"offers":{"email":false}}

  • frequencystring | null
    Omit to keep.

    values: "weekly", "monthly", null

  • paused_untilstring (date-time) | null
    Pause marketing messages until this time (within a year); null resumes; omit to keep.
  • unsubscribe_allboolean
    Unsubscribe from all marketing messages in every channel, including channels connected or addressable later; other fields are ignored. Subscribing to a channel afterwards (here, by PUT /profiles/{type}/{value}/consents or by a push permission) opens only that channel.
  • languagestring
    Language of topic names in the response.
  • adsboolean
    Advertising consent: allow (true) or deny (false) sending the profile data to ad platforms. Applies only when the project has an ad platform connected (ads in the response is not null).
Request body example
{
  "topics": {
    "news": {
      "email": true
    },
    "offers": {
      "email": false
    }
  },
  "frequency": "weekly",
  "paused_until": "2026-01-01T10:00:00Z",
  "unsubscribe_all": true,
  "language": "string",
  "ads": true
}

Responses

  • 200OK

    ProfilePreferences

    • profile_idinteger
    • languagestring
      Language of topic names.

      example: "en"

    • channelsobject[]
      Channels the profile receives or can receive messages in: channels of its consents and messages of the last year, and channels of active integrations it has an address for.
      • keystring

        example: "email"

      • namestring
        Name of the channel in the requested language, lower case as inside a sentence.

        example: "email"

      • blockedboolean
        Hard block (the address does not exist, the bot was stopped): read only.
    • unsubscribed_allboolean
      The profile unsubscribed from marketing messages in all channels (unsubscribe_all or the preference center): channels without their own subscription stay closed.
    • adsboolean | null
      Advertising consent; null — the project has no ad platform connected, nothing to ask.
    • topicsobject[]
      Visible subscription topics.
      • keystring

        example: "news"

      • namestring
      • descriptionstring
      • channelsobject
        Channel key → subscribed (true/false), null — the topic is not offered in this channel.
    • frequencystring | null
      At most one marketing message per week or month across channels; null — as usual.

      values: "weekly", "monthly", null

    • paused_untilstring (date-time) | null
      Marketing messages are paused until this time.
    • preferences_urlstring (uri)
      Signed link to the preference center page of this profile, valid for 30 days — for a «Manage subscriptions» link in the store account.
    • preferences_url_expires_atstring (date-time)
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Wallet card link of a profile

get/profiles/{type}/{value}/wallet

Signed link to the page where the customer adds the loyalty card to Apple Wallet or Google Wallet (ADR-177) — for the account area of the store, valid for 90 days — and the profile's cards: platform, card number, whether the card is installed. wallet_url is null when the project has no Wallet cards (no wallet integration or the plan has no wallet feature).

Key: secretKey · Permissions: profiles.read

Parameters

  • typepathstringrequired

    values: "user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"

  • valuepathstringrequired
    Normalized like at ingestion (lower-case email, E.164 phone).
  • languagequerystring
    Language of topic names; the project default when omitted.

Responses

  • 200OK
    • wallet_urlstring (uri) | null
    • wallet_url_expires_atstring (date-time) | null
    • platformsstring[]
    • passesobject[]
      • platformstring

        values: "apple", "google"

      • card_numberstring
      • installedboolean
      • installed_atstring (date-time) | null
      • removed_atstring (date-time) | null
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Subscription topics of the project

get/subscription-topics

Topics of the preference center with names and descriptions in the project languages.

Key: secretKey · Permissions: profiles.read

Responses

  • 200OK
    • dataobject[]
      • keystring
      • textsobject
        Language → {name, description}.
      • channelsstring[] | null
        null — all channels.
      • visibleboolean
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 429Rate limit or monthly event quota exceeded · Error

Products

Create or update products and categories

post/products

Key: secretKey · Permissions: products.write

Request bodyrequired

  • itemsProductInput[]required

    items: ≤ 1000

  • categoriesobject[]

    items: ≤ 1000

    • idstringrequired
    • namestringrequired
    • parent_idstring | null
    • translationsobject
      Category name by language (BCP 47 tag → {name}).

      keys: ≤ 20

Request body example
{
  "items": [
    {
      "id": "string",
      "name": "string",
      "url": "https://example.com",
      "image": "https://example.com",
      "price": 0,
      "old_price": 0,
      "currency": "string",
      "available": true,
      "stock": 0,
      "category_ids": [
        "string"
      ],
      "brand": "string",
      "description": "string",
      "params": {},
      "translations": {}
    }
  ],
  "categories": [
    {
      "id": "string",
      "name": "string",
      "parent_id": "string",
      "translations": {}
    }
  ]
}

Responses

  • 200Saved
    • savedinteger
    • categoriesinteger
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Delete products

delete/products

Key: secretKey · Permissions: products.write

Request bodyrequired

  • idsstring[]required

    items: 1–1000

Request body example
{
  "ids": [
    "string"
  ]
}

Responses

  • 200Deleted
    • deletedinteger
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Published reviews of a product

get/reviews

Write key (tracker review block) or secret key. Only published reviews, newest first, 10 per page; rating and count — over all published reviews of the product, distribution — number of reviews per score. product gives the name and link for schema.org markup. Cached for 1 minute. Needs the “Product reviews” tariff feature.

Key: writeKey or secretKey

Parameters

  • productquerystringrequired
    Product id from the catalog.

    length: ≤ 128

  • pagequeryinteger

    default: 1 · range: 1–1000

  • languagequerystring
    Language of the product name.

    length: ≤ 35

Responses

  • 200Reviews
    • productobject
      • idstring
      • namestring
      • urlstring | null
      • imagestring | null
    • ratingnumber | null
      Average score, null without reviews.
    • countinteger
    • distributionobject
      Score (5…1) → number of reviews.
    • reviewsobject[]
      • idinteger
      • ratinginteger

        range: 1–5

      • titlestring | null
      • textstring | null
      • authorstring | null
      • languagestring | null
      • published_atstring (date-time) | null
    • pageinteger
    • moreboolean
  • 401Missing, invalid or revoked key · Error
  • 402The tariff has no product reviews
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Add a product review

post/reviews

Key: secretKey · Permissions: products.write

Request bodyrequired

  • productstringrequired
    Product id from the catalog.

    length: ≤ 128

  • identityIdentityRefrequired
  • ratingintegerrequired

    range: 1–5

  • titlestring

    length: ≤ 120

  • textstring

    length: ≤ 2000

  • authorstring
    Name shown with the review.

    length: ≤ 60

  • languagestring

    length: ≤ 35

  • publishboolean

    default: false

  • datestring (date-time)
    Date of a moved review (with publish).
Request body example
{
  "product": "string",
  "identity": {
    "type": "user_id",
    "value": "string"
  },
  "rating": 1,
  "title": "string",
  "text": "string",
  "author": "string",
  "language": "string",
  "publish": false,
  "date": "2026-01-01T10:00:00Z"
}

Responses

  • 201Saved
    • idinteger
    • statusstring

      values: "pending", "published"

  • 401Missing, invalid or revoked key · Error
  • 402The tariff has no product reviews
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Ask AI about a product

post/products/questions

Answers a shopper's question about one product from its card (name, description, characteristics, industry attributes, price, stock) and the shop knowledge base, in the language of the question (ADR-132). Charged to the project balance by tokens like AI in chat; the same question about an unchanged product in the same language is answered from a cache for a day without charge. Limited per visitor (5 a minute, 50 a day). Records the event $product_question for the visitor.

Used by the product question widget of the tracker; not part of the SDKs.

With async: true an answer from the cache comes at once (200); otherwise the model answers in the background and the response is 202 with id — get the result with GET /products/questions/result. Without it the answer comes in the same request.

Key: writeKey or secretKey

Request bodyrequired

  • product_idstringrequired
    Product id in the catalog (id from the feed or the products API)

    length: ≤ 128

  • questionstringrequired

    length: ≤ 500

  • anonymousIdstringrequired

    length: ≤ 255

  • userIdstring

    length: ≤ 255

  • userHashstring
    Signature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.

    length: ≤ 128

  • languagestring
    Language of the page (BCP 47); the answer follows the language of the question

    length: ≤ 35

  • asyncboolean
    Answer in the background: 202 with id instead of waiting for the model (the tracker widget does so)
Request body example
{
  "product_id": "string",
  "question": "string",
  "anonymousId": "string",
  "userId": "string",
  "userHash": "string",
  "language": "string",
  "async": true
}

Responses

  • 200Answer
    • answerstring
    • answeredboolean
      false — the product card and the shop knowledge do not answer the question; the answer says so and suggests asking the staff
    • sourcesobject[]
      • titlestring
      • urlstring | null
  • 202Accepted with `async: true`: the model answers in the background
    • pendingboolean
    • idstring
      Token of the result for GET /products/questions/result, kept for 10 minutes
  • 402AI is not available for the project: no paid plan, no balance, spend limit reached (`reason`)
    • messagestring
    • reasonstring
  • 404No such product
    • messagestring
    • reasonstring
  • 429Too many questions from this visitor
    • messagestring
    • reasonstring
  • 502The AI model did not answer
    • messagestring
    • reasonstring
  • 503AI is not configured on the platform
    • messagestring
    • reasonstring

Result of a product question answered in the background

get/products/questions/result

Result of POST /products/questions with async: true (ADR-132): 202 while the model is answering, then the answer as for a question answered at once. The token is kept for 10 minutes.

Used by the product question widget of the tracker; not part of the SDKs.

Key: writeKey or secretKey

Parameters

  • idquerystringrequired

    length: 40–40

Responses

  • 200Answer
    • answerstring
    • answeredboolean
      false — the product card and the shop knowledge do not answer the question; the answer says so and suggests asking the staff
    • sourcesobject[]
      • titlestring
      • urlstring | null
  • 202The model is still answering
    • pendingboolean
  • 402AI is not available for the project (`reason`)
    • messagestring
    • reasonstring
  • 404No such result: unknown or expired token
    • messagestring
    • reasonstring
  • 502The AI model did not answer
    • messagestring
    • reasonstring
  • 503AI is turned off or not configured on the platform (`reason`)
    • messagestring
    • reasonstring

Suggested questions about a product

get/products/questions/suggested

Three short typical shopper questions for products of the category, in the language of the page (ADR-132). Generated by AI once per category and language and kept for 30 days; empty when AI is not available.

Used by the product question widget of the tracker; not part of the SDKs.

Key: writeKey or secretKey

Parameters

  • product_idquerystringrequired

    length: ≤ 128

  • languagequerystring

    length: ≤ 35

Responses

  • 200Questions
    • questionsstring[]
  • 404No such product
    • messagestring
    • reasonstring

Product question widget settings

get/products/questions/widget

Settings of the product question widget for the tracker (ADR-132): mode, suggestions, appearance and texts in the visitor's language. enabled: false when the widget is off in the site settings, AI is not configured or not paid for — the tracker then does not load the widget. Cached for 5 minutes when off, 1 minute when on.

Used by the tracker; not part of the SDKs.

Key: writeKey or secretKey

Parameters

  • languagequerystring

    length: ≤ 35

Responses

  • 200Widget settings
    • enabledbooleanrequired
    • modestring

      values: "block", "chat"

    • chatboolean
      Online chat is on: the block offers to ask the staff
    • suggestionsboolean
    • accentstring

      example: "#4f46e5"

    • radiusinteger

      range: 0–24

    • textsobject

Stores

List stores

get/stores

Key: secretKey · Permissions: products.read

Responses

  • 200Stores
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 429Rate limit or monthly event quota exceeded · Error

Create or update stores

post/stores

Key: secretKey · Permissions: products.write

Request bodyrequired

  • itemsStore[]required

    items: 1–1000

Request body example
{
  "items": [
    {
      "id": "string",
      "name": "string",
      "city": "string",
      "address": "string"
    }
  ]
}

Responses

  • 200Saved
    • savedinteger
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Delete stores

delete/stores

Key: secretKey · Permissions: products.write

Request bodyrequired

  • idsstring[]required

    items: 1–1000

Request body example
{
  "ids": [
    "string"
  ]
}

Responses

  • 200Deleted
    • deletedinteger
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Catalog

Events seen in the project with their properties

get/catalog/events

Key: secretKey · Permissions: events.read

Responses

  • 200OK
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 429Rate limit or monthly event quota exceeded · Error

Profile traits of the project

get/catalog/traits

Key: secretKey · Permissions: events.read

Responses

  • 200OK
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 429Rate limit or monthly event quota exceeded · Error

Event schema of the project

get/event-schema

Expected events with their properties (ADR-176): type, whether the property is required and the allowed values. enabled — whether incoming events are checked against the schema.

Key: secretKey · Permissions: events.read

Responses

  • 200OK

    EventSchema

    • enabledboolean
      Check incoming events against the schema
    • eventsobject[]

      items: ≤ 1000

      • namestringrequired
        Event name (system $… events are not allowed)

        length: ≤ 255

      • labelstring | null

        length: ≤ 255

      • descriptionstring | null

        length: ≤ 1000

      • propertiesobject[]

        items: ≤ 200

        • keystringrequired

          length: ≤ 255

        • typestringrequired

          values: "string", "number", "boolean", "datetime", "list", "object"

        • requiredboolean

          default: false

        • valuesstring | number[] | null
          Allowed values (strings or numbers; only for string and number properties)

          items: ≤ 100

          One of:

        • descriptionstring | null

          length: ≤ 1000

  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 429Rate limit or monthly event quota exceeded · Error

Replace the event schema

put/event-schema

Replaces the schema with the listed events: they and their properties become expected (missing ones are added to the catalog), other events leave the schema but stay in the catalog. Without events only enabled changes. label is changed only when present. Events that break the schema are still accepted: violations are counted for 7 days (GET /event-schema/violations) and start over after every change. Requires the event_schema plan feature (402 otherwise).

Key: secretKey · Permissions: events.manage_schema

Request bodyrequired

EventSchema

  • enabledboolean
    Check incoming events against the schema
  • eventsobject[]

    items: ≤ 1000

    • namestringrequired
      Event name (system $… events are not allowed)

      length: ≤ 255

    • labelstring | null

      length: ≤ 255

    • descriptionstring | null

      length: ≤ 1000

    • propertiesobject[]

      items: ≤ 200

      • keystringrequired

        length: ≤ 255

      • typestringrequired

        values: "string", "number", "boolean", "datetime", "list", "object"

      • requiredboolean

        default: false

      • valuesstring | number[] | null
        Allowed values (strings or numbers; only for string and number properties)

        items: ≤ 100

        One of:

      • descriptionstring | null

        length: ≤ 1000

Request body example
{
  "enabled": true,
  "events": [
    {
      "name": "string",
      "label": "string",
      "description": "string",
      "properties": [
        {
          "key": "string",
          "type": "string",
          "required": false,
          "values": [
            "string"
          ],
          "description": "string"
        }
      ]
    }
  ]
}

Responses

  • 200Saved

    EventSchema

    • enabledboolean
      Check incoming events against the schema
    • eventsobject[]

      items: ≤ 1000

      • namestringrequired
        Event name (system $… events are not allowed)

        length: ≤ 255

      • labelstring | null

        length: ≤ 255

      • descriptionstring | null

        length: ≤ 1000

      • propertiesobject[]

        items: ≤ 200

        • keystringrequired

          length: ≤ 255

        • typestringrequired

          values: "string", "number", "boolean", "datetime", "list", "object"

        • requiredboolean

          default: false

        • valuesstring | number[] | null
          Allowed values (strings or numbers; only for string and number properties)

          items: ≤ 100

          One of:

        • descriptionstring | null

          length: ≤ 1000

  • 401Missing, invalid or revoked key · Error
  • 402The tariff has no event schema
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Event schema violations for 7 days

get/event-schema/violations

Violations of the event schema, latest first: kind, event, property, count for 7 days, last time and the last example (the value type, or the value itself for unexpected_value; masked without the profiles.pii permission). Empty while the check is off.

Key: secretKey · Permissions: events.read

Responses

  • 200OK
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 429Rate limit or monthly event quota exceeded · Error

Segments

List segments

get/segments

Key: secretKey · Permissions: segments.read

Parameters

  • limitqueryinteger

    default: 50 · range: 1–200

  • cursorquerystring

Responses

  • 200OK
    • dataSegment[]required
    • next_cursorstring | nullrequired
      Pass as cursor to get the next page; null on the last page.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 429Rate limit or monthly event quota exceeded · Error

Create a segment

post/segments

Dynamic segments are computed asynchronously; poll status. Rules use the same DSL as the segment builder (docs/architecture/segmentation.md).

Key: secretKey · Permissions: segments.write

Parameters

  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

SegmentInput

  • namestringrequired

    length: ≤ 120

  • descriptionstring | null
  • typestringrequired

    values: "dynamic", "static"

  • realtimeboolean
  • schedule_minutesinteger

    values: 15, 30, 60, 180, 360, 720, 1440

  • rulesobject
Request body example
{
  "name": "string",
  "description": "string",
  "type": "dynamic",
  "realtime": true,
  "schedule_minutes": 15,
  "rules": {}
}

Responses

  • 201Created

    SegmentDetail

    All fields of Segment:

    • rulesobject | null
      Rule tree: {"op": "and|or", "children": [...]}
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Get a segment with its rules

get/segments/{segment}

Key: secretKey · Permissions: segments.read

Parameters

  • segmentpathintegerrequired

Responses

  • 200OK

    SegmentDetail

    All fields of Segment:

    • rulesobject | null
      Rule tree: {"op": "and|or", "children": [...]}
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Update a segment (partial)

patch/segments/{segment}

Changing rules of a dynamic segment queues a recomputation.

Key: secretKey · Permissions: segments.write

Parameters

  • segmentpathintegerrequired

Request bodyrequired

SegmentPatch

  • namestring

    length: ≤ 120

  • descriptionstring | null
  • realtimeboolean
  • schedule_minutesinteger
  • rulesobject
Request body example
{
  "name": "string",
  "description": "string",
  "realtime": true,
  "schedule_minutes": 0,
  "rules": {}
}

Responses

  • 200OK

    SegmentDetail

    All fields of Segment:

    • rulesobject | null
      Rule tree: {"op": "and|or", "children": [...]}
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Delete a segment

delete/segments/{segment}

Fails with 422 while other segments reference it.

Key: secretKey · Permissions: segments.write

Parameters

  • segmentpathintegerrequired

Responses

  • 204Deleted
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Queue a recomputation of a dynamic segment

post/segments/{segment}/compute

Key: secretKey · Permissions: segments.write

Parameters

  • segmentpathintegerrequired

Responses

  • 202Queued
    • queuedboolean
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422The request cannot be applied in the current state · Error
  • 429Rate limit or monthly event quota exceeded · Error

Segment members, latest entered first

get/segments/{segment}/members

Key: secretKey · Permissions: segments.read

Parameters

  • segmentpathintegerrequired
  • limitqueryinteger

    default: 50 · range: 1–200

  • cursorquerystring

Responses

  • 200OK
    • dataobject[]required
      • profile_idinteger
      • entered_atstring (date-time)
    • next_cursorstring | nullrequired
      Pass as cursor to get the next page; null on the last page.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Add profiles to a static segment

post/segments/{segment}/members

Key: secretKey · Permissions: segments.write

Parameters

  • segmentpathintegerrequired
  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

IdentitiesInput

Request body example
{
  "identities": [
    {
      "type": "user_id",
      "value": "string"
    }
  ]
}

Responses

  • 200OK
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Remove profiles from a static segment

delete/segments/{segment}/members

Key: secretKey · Permissions: segments.write

Parameters

  • segmentpathintegerrequired

Request bodyrequired

IdentitiesInput

Request body example
{
  "identities": [
    {
      "type": "user_id",
      "value": "string"
    }
  ]
}

Responses

  • 200OK
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Whether a profile is a member

get/segments/{segment}/members/{type}/{value}

Key: secretKey · Permissions: segments.read

Parameters

  • segmentpathintegerrequired
  • typepathstringrequired

    values: "user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"

  • valuepathstringrequired
    Normalized like at ingestion (lower-case email, E.164 phone).

Responses

  • 200OK
    • profile_idinteger
    • memberboolean
    • entered_atstring (date-time) | null
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Journeys

List journeys

get/journeys

Key: secretKey · Permissions: journeys.read

Parameters

  • limitqueryinteger

    default: 50 · range: 1–200

  • cursorquerystring
  • statusquerystring

    values: "draft", "active", "paused", "archived"

Responses

  • 200OK
    • dataJourney[]required
    • next_cursorstring | nullrequired
      Pass as cursor to get the next page; null on the last page.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 429Rate limit or monthly event quota exceeded · Error

Create a journey draft

post/journeys

The draft may be incomplete; it is validated on publish. Graph and entry use the editor format (docs/architecture/journeys.md).

Key: secretKey · Permissions: journeys.write

Parameters

  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

JourneyInput

  • namestringrequired

    length: ≤ 120

  • descriptionstring | null
  • graphobject
    • nodesarray

      items: ≤ 200

    • edgesarray

      items: ≤ 400

  • entryobject
Request body example
{
  "name": "string",
  "description": "string",
  "graph": {
    "nodes": [],
    "edges": []
  },
  "entry": {}
}

Responses

  • 201Created

    JourneyDetail

    All fields of Journey:

    • draftobject
      • graphobject
      • entryobject
    • publishedobject | null
      • graphobject
      • entryobject
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Get a journey with its draft and published version

get/journeys/{journey}

Key: secretKey · Permissions: journeys.read

Parameters

  • journeypathintegerrequired

Responses

  • 200OK

    JourneyDetail

    All fields of Journey:

    • draftobject
      • graphobject
      • entryobject
    • publishedobject | null
      • graphobject
      • entryobject
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Update the draft (partial)

patch/journeys/{journey}

Key: secretKey · Permissions: journeys.write

Parameters

  • journeypathintegerrequired

Request bodyrequired

JourneyPatch

  • namestring

    length: ≤ 120

  • descriptionstring | null
  • graphobject
  • entryobject
Request body example
{
  "name": "string",
  "description": "string",
  "graph": {},
  "entry": {}
}

Responses

  • 200OK

    JourneyDetail

    All fields of Journey:

    • draftobject
      • graphobject
      • entryobject
    • publishedobject | null
      • graphobject
      • entryobject
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Validate the draft without publishing

post/journeys/{journey}/validate

422 lists errors by path, e.g. graph.nodes.2.data.template_id.

Key: secretKey · Permissions: journeys.read

Parameters

  • journeypathintegerrequired

Responses

  • 200OK
    • validboolean
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Launch readiness of the draft

get/journeys/{journey}/readiness

Checks the draft before publishing: errors (publishing fails), warnings (messages will not reach recipients or reach the wrong ones: no unsubscribe link in a marketing email, a template does not render, a missing language version, an unverified sending domain, an integration error, an empty segment or one covering almost all profiles, a goal event never seen) and notes (no goal or conversion window, segment not computed yet).

Key: secretKey · Permissions: journeys.read

Parameters

  • journeypathintegerrequired

Responses

  • 200OK

    LaunchReadiness

    • readybooleanrequired
      No errors: the launch will pass.
    • clearbooleanrequired
      No errors and no warnings.
    • checksobject[]required
      • keystringrequired
        config, archived, quota, sending_domain, integration, untranslated, template_error, unsubscribe, deliverability, segment_pending, segment_empty, segment_broad, goal_missing, goal_unseen, goal_window
      • levelstringrequired

        values: "error", "warning", "info"

      • messagestringrequired
        Text in the language of the request
      • pathstring
        Field of a config error, e.g. variants.0.template_id
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Publish the draft as a new version

post/journeys/{journey}/publish

First publish activates the journey and counts towards the plan's active journeys limit.

Key: secretKey · Permissions: journeys.publish

Parameters

  • journeypathintegerrequired
  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Responses

  • 200OK

    JourneyDetail

    All fields of Journey:

    • draftobject
      • graphobject
      • entryobject
    • publishedobject | null
      • graphobject
      • entryobject
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Pause: no new entries, participants stay

post/journeys/{journey}/pause

Body {"exit_all": true} also exits all participants. Only active journeys.

Key: secretKey · Permissions: journeys.publish

Parameters

  • journeypathintegerrequired
  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request body

  • exit_allboolean
Request body example
{
  "exit_all": true
}

Responses

  • 200OK

    Journey

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      values: "draft", "active", "paused", "archived"

    • versioninteger | null
    • next_run_atstring (date-time) | null
    • approval_statusstring
      Approval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.

      values: "pending", "approved", "returned"

    • created_atstring (date-time)
    • updated_atstring (date-time)
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Resume a paused journey

post/journeys/{journey}/resume

Counts towards the active journeys limit.

Key: secretKey · Permissions: journeys.publish

Parameters

  • journeypathintegerrequired
  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Responses

  • 200OK

    Journey

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      values: "draft", "active", "paused", "archived"

    • versioninteger | null
    • next_run_atstring (date-time) | null
    • approval_statusstring
      Approval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.

      values: "pending", "approved", "returned"

    • created_atstring (date-time)
    • updated_atstring (date-time)
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Archive: all participants exit

post/journeys/{journey}/archive

Irreversible.

Key: secretKey · Permissions: journeys.publish

Parameters

  • journeypathintegerrequired
  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Responses

  • 200OK

    Journey

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      values: "draft", "active", "paused", "archived"

    • versioninteger | null
    • next_run_atstring (date-time) | null
    • approval_statusstring
      Approval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.

      values: "pending", "approved", "returned"

    • created_atstring (date-time)
    • updated_atstring (date-time)
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Submit a journey for approval

post/journeys/{journey}/approval/request

Sends the journey to review when the project requires approval before launch; approvers get an email. Optional comment.

Key: secretKey · Permissions: journeys.write

Parameters

  • journeypathintegerrequired

Request body

  • commentstring

    length: ≤ 1000

Request body example
{
  "comment": "string"
}

Responses

  • 200OK
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Approve a journey

post/journeys/{journey}/approval/approve

Approves a journey on review. Any later change to the journey (or, for campaigns, to its templates) sends it back to review.

Key: secretKey · Permissions: journeys.approve

Parameters

  • journeypathintegerrequired

Request body

  • commentstring

    length: ≤ 1000

Request body example
{
  "comment": "string"
}

Responses

  • 200OK
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Return a journey for changes

post/journeys/{journey}/approval/return

Sends a journey on review back to its author; comment is required.

Key: secretKey · Permissions: journeys.approve

Parameters

  • journeypathintegerrequired

Request bodyrequired

  • commentstringrequired

    length: ≤ 1000

Request body example
{
  "comment": "string"
}

Responses

  • 200OK
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Journey participations, newest first

get/journeys/{journey}/enrollments

Key: secretKey · Permissions: journeys.read

Parameters

  • journeypathintegerrequired
  • limitqueryinteger

    default: 50 · range: 1–200

  • cursorquerystring
  • statusquerystring

    values: "active", "waiting", "completed", "exited", "failed"

Responses

  • 200OK
    • dataEnrollment[]required
    • next_cursorstring | nullrequired
      Pass as cursor to get the next page; null on the last page.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Funnel, goals and A/B branches for a period

get/journeys/{journey}/report

Key: secretKey · Permissions: journeys.read, analytics.read

Parameters

  • journeypathintegerrequired
  • periodqueryinteger

    values: 7, 30, 90 · default: 30

Responses

  • 200OK

    object

  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Enroll a profile into a journey with the API trigger

post/journeys/{journey}/enroll

Key: secretKey · Permissions: journeys.write

Parameters

  • journeypathintegerrequired
  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

  • identityIdentityRefrequired
  • dataobject
    Available in templates as context.data.
  • idempotency_keystring

    length: ≤ 150

Request body example
{
  "identity": {
    "type": "user_id",
    "value": "string"
  },
  "data": {},
  "idempotency_key": "string"
}

Responses

  • 200Not enrolled (repeat key, re-entry policy, audience or limit)

    EnrollResult

    • enrolledboolean
    • enrollment_idinteger | null
    • profile_idinteger
  • 201Enrolled

    EnrollResult

    • enrolledboolean
    • enrollment_idinteger | null
    • profile_idinteger
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 409The request cannot be applied in the current state · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Templates

List message templates

get/templates

Key: secretKey · Permissions: templates.read

Parameters

  • limitqueryinteger

    default: 50 · range: 1–200

  • cursorquerystring
  • channelquerystring
    Only templates of this channel.

Responses

  • 200OK
    • dataMessageTemplate[]required
    • next_cursorstring | nullrequired
      Pass as cursor to get the next page; null on the last page.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 429Rate limit or monthly event quota exceeded · Error

Create a message template

post/templates

Every language version is checked against the channel schema and the Twig sandbox.

Key: secretKey · Permissions: templates.write

Parameters

  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

MessageTemplateInput

  • namestringrequired

    length: ≤ 120

  • channel_keystringrequired
    Channel of the template; cannot be changed later.
  • topicstring

    default: "marketing" · length: ≤ 64 · pattern: ^[a-z0-9_-]+$

  • transactionalboolean

    default: false

  • languagestring
    Main language of content; the project default language if omitted.

    length: ≤ 16 · example: "de"

  • contentobjectrequired
    Fields of the channel message schema, e.g. subject, html and text for email; string fields are Twig templates.
  • translationsobject
    Other language versions; each is validated like content. Omit to keep the stored versions, pass {} to delete them.

    keys: ≤ 50

Request body example
{
  "name": "string",
  "channel_key": "string",
  "topic": "marketing",
  "transactional": false,
  "language": "de",
  "content": {},
  "translations": {}
}

Responses

  • 201Created

    MessageTemplate

    • idinteger
    • namestring
    • channelstring

      example: "email"

    • topicstring
      Subscription topic the message belongs to.
    • transactionalboolean
    • languagestring
      Main language of content: recipients whose profile language has no version get it.

      length: ≤ 16 · example: "de"

    • contentobject
      Fields of the channel message schema, e.g. subject, html and text for email; string fields are Twig templates.
    • translationsobject
      Other language versions: language tag → content. A recipient gets the version for the language profile trait (exact tag, then the base language, then another variant of it), otherwise content.
    • versioninteger
      Grows when any language version changes.
    • created_atstring (date-time) | null
    • updated_atstring (date-time) | null
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Get a message template

get/templates/{template}

Key: secretKey · Permissions: templates.read

Parameters

  • templatepathintegerrequired

Responses

  • 200OK

    MessageTemplate

    • idinteger
    • namestring
    • channelstring

      example: "email"

    • topicstring
      Subscription topic the message belongs to.
    • transactionalboolean
    • languagestring
      Main language of content: recipients whose profile language has no version get it.

      length: ≤ 16 · example: "de"

    • contentobject
      Fields of the channel message schema, e.g. subject, html and text for email; string fields are Twig templates.
    • translationsobject
      Other language versions: language tag → content. A recipient gets the version for the language profile trait (exact tag, then the base language, then another variant of it), otherwise content.
    • versioninteger
      Grows when any language version changes.
    • created_atstring (date-time) | null
    • updated_atstring (date-time) | null
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Update a message template (partial)

patch/templates/{template}

Journeys and campaigns that use the template send the new content from the next message on.

Key: secretKey · Permissions: templates.write

Parameters

  • templatepathintegerrequired

Request bodyrequired

  • namestring

    length: ≤ 120

  • topicstring

    default: "marketing" · length: ≤ 64 · pattern: ^[a-z0-9_-]+$

  • transactionalboolean

    default: false

  • languagestring
    Main language of content; the project default language if omitted.

    length: ≤ 16 · example: "de"

  • contentobject
    Fields of the channel message schema, e.g. subject, html and text for email; string fields are Twig templates.
  • translationsobject
    Other language versions; each is validated like content. Omit to keep the stored versions, pass {} to delete them.

    keys: ≤ 50

Request body example
{
  "name": "string",
  "topic": "marketing",
  "transactional": false,
  "language": "de",
  "content": {},
  "translations": {}
}

Responses

  • 200OK

    MessageTemplate

    • idinteger
    • namestring
    • channelstring

      example: "email"

    • topicstring
      Subscription topic the message belongs to.
    • transactionalboolean
    • languagestring
      Main language of content: recipients whose profile language has no version get it.

      length: ≤ 16 · example: "de"

    • contentobject
      Fields of the channel message schema, e.g. subject, html and text for email; string fields are Twig templates.
    • translationsobject
      Other language versions: language tag → content. A recipient gets the version for the language profile trait (exact tag, then the base language, then another variant of it), otherwise content.
    • versioninteger
      Grows when any language version changes.
    • created_atstring (date-time) | null
    • updated_atstring (date-time) | null
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Delete a message template

delete/templates/{template}

Messages already sent keep their content; journey steps and campaign variants that use the template stop being valid.

Key: secretKey · Permissions: templates.write

Parameters

  • templatepathintegerrequired

Responses

  • 204Deleted
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Campaigns

List campaigns

get/campaigns

Key: secretKey · Permissions: campaigns.read

Parameters

  • limitqueryinteger

    default: 50 · range: 1–200

  • cursorquerystring

Responses

  • 200OK
    • dataCampaign[]required
    • next_cursorstring | nullrequired
      Pass as cursor to get the next page; null on the last page.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 429Rate limit or monthly event quota exceeded · Error

Create a campaign draft

post/campaigns

The draft may be incomplete; readiness is checked on schedule.

Key: secretKey · Permissions: campaigns.write

Parameters

  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

CampaignInput

Request body example
{
  "name": "string",
  "description": "string",
  "integration_id": 0,
  "audience": {
    "segment_ids": [
      0
    ],
    "exclude_segment_ids": [
      0
    ],
    "ignore_control_group": true
  },
  "variants": [
    {
      "key": "string",
      "template_id": 0,
      "percent": 1
    }
  ],
  "ab": {
    "mode": "test",
    "test_percent": 5,
    "metric": "opened",
    "wait": {
      "amount": 1,
      "unit": "hour"
    }
  },
  "schedule": {
    "type": "now",
    "at": "2026-11-01T10:00",
    "repeat": "daily",
    "time": "10:00",
    "weekdays": [
      1
    ],
    "day_of_month": 1,
    "start_date": "2026-01-01",
    "end_date": "2026-01-01",
    "local_time": true,
    "best_time": true
  },
  "rate_per_minute": 10,
  "goal": {
    "event": "string",
    "within": {
      "amount": 1,
      "unit": "hour"
    }
  }
}

Responses

  • 201Created

    Campaign

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      values: "draft", "scheduled", "sending", "sent", "paused", "cancelled"

    • integration_idinteger | null
    • channelstring | null
    • rate_per_minuteinteger | null
    • next_run_atstring (date-time) | null
    • last_run_atstring (date-time) | null
    • approval_statusstring
      Approval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.

      values: "pending", "approved", "returned"

    • created_atstring (date-time)
    • updated_atstring (date-time)
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Get a campaign

get/campaigns/{campaign}

Key: secretKey · Permissions: campaigns.read

Parameters

  • campaignpathintegerrequired

Responses

  • 200OK

    Campaign

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      values: "draft", "scheduled", "sending", "sent", "paused", "cancelled"

    • integration_idinteger | null
    • channelstring | null
    • rate_per_minuteinteger | null
    • next_run_atstring (date-time) | null
    • last_run_atstring (date-time) | null
    • approval_statusstring
      Approval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.

      values: "pending", "approved", "returned"

    • created_atstring (date-time)
    • updated_atstring (date-time)
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Update a campaign (partial)

patch/campaigns/{campaign}

Only draft, scheduled or paused campaigns; a scheduled campaign is re-checked and its next run recomputed.

Key: secretKey · Permissions: campaigns.write

Parameters

  • campaignpathintegerrequired

Request bodyrequired

Request body example
{
  "name": "string",
  "description": "string",
  "integration_id": 0,
  "audience": {
    "segment_ids": [
      0
    ],
    "exclude_segment_ids": [
      0
    ],
    "ignore_control_group": true
  },
  "variants": [
    {
      "key": "string",
      "template_id": 0,
      "percent": 1
    }
  ],
  "ab": {
    "mode": "test",
    "test_percent": 5,
    "metric": "opened",
    "wait": {
      "amount": 1,
      "unit": "hour"
    }
  },
  "schedule": {
    "type": "now",
    "at": "2026-11-01T10:00",
    "repeat": "daily",
    "time": "10:00",
    "weekdays": [
      1
    ],
    "day_of_month": 1,
    "start_date": "2026-01-01",
    "end_date": "2026-01-01",
    "local_time": true,
    "best_time": true
  },
  "rate_per_minute": 10,
  "goal": {
    "event": "string",
    "within": {
      "amount": 1,
      "unit": "hour"
    }
  }
}

Responses

  • 200OK

    Campaign

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      values: "draft", "scheduled", "sending", "sent", "paused", "cancelled"

    • integration_idinteger | null
    • channelstring | null
    • rate_per_minuteinteger | null
    • next_run_atstring (date-time) | null
    • last_run_atstring (date-time) | null
    • approval_statusstring
      Approval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.

      values: "pending", "approved", "returned"

    • created_atstring (date-time)
    • updated_atstring (date-time)
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Delete a campaign

delete/campaigns/{campaign}

Fails with 422 while scheduled or sending: cancel it first.

Key: secretKey · Permissions: campaigns.write

Parameters

  • campaignpathintegerrequired

Responses

  • 204Deleted
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Campaign report: last runs with per-variant stats

get/campaigns/{campaign}/report

Key: secretKey · Permissions: campaigns.read

Parameters

  • campaignpathintegerrequired

Responses

  • 200OK
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Launch readiness of the campaign

get/campaigns/{campaign}/readiness

Checks the campaign before scheduling: errors (scheduling fails), warnings (messages will not reach recipients or reach the wrong ones: no unsubscribe link in a marketing email, a template does not render, a missing language version, an unverified sending domain, an integration error, an empty segment or one covering almost all profiles, a goal event never seen) and notes (no goal or conversion window, segment not computed yet).

Key: secretKey · Permissions: campaigns.read

Parameters

  • campaignpathintegerrequired

Responses

  • 200OK

    LaunchReadiness

    • readybooleanrequired
      No errors: the launch will pass.
    • clearbooleanrequired
      No errors and no warnings.
    • checksobject[]required
      • keystringrequired
        config, archived, quota, sending_domain, integration, untranslated, template_error, unsubscribe, deliverability, segment_pending, segment_empty, segment_broad, goal_missing, goal_unseen, goal_window
      • levelstringrequired

        values: "error", "warning", "info"

      • messagestringrequired
        Text in the language of the request
      • pathstring
        Field of a config error, e.g. variants.0.template_id
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Schedule (or launch) a campaign

post/campaigns/{campaign}/schedule

Draft or paused campaign without a paused run. Checks readiness (channel, templates, audience, goal, schedule); now starts within a minute.

Key: secretKey · Permissions: campaigns.send

Parameters

  • campaignpathintegerrequired
  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Responses

  • 200OK

    Campaign

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      values: "draft", "scheduled", "sending", "sent", "paused", "cancelled"

    • integration_idinteger | null
    • channelstring | null
    • rate_per_minuteinteger | null
    • next_run_atstring (date-time) | null
    • last_run_atstring (date-time) | null
    • approval_statusstring
      Approval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.

      values: "pending", "approved", "returned"

    • created_atstring (date-time)
    • updated_atstring (date-time)
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Pause a campaign

post/campaigns/{campaign}/pause

The current run stops queueing messages; next runs do not start.

Key: secretKey · Permissions: campaigns.send

Parameters

  • campaignpathintegerrequired
  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Responses

  • 200OK

    Campaign

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      values: "draft", "scheduled", "sending", "sent", "paused", "cancelled"

    • integration_idinteger | null
    • channelstring | null
    • rate_per_minuteinteger | null
    • next_run_atstring (date-time) | null
    • last_run_atstring (date-time) | null
    • approval_statusstring
      Approval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.

      values: "pending", "approved", "returned"

    • created_atstring (date-time)
    • updated_atstring (date-time)
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Resume a paused campaign

post/campaigns/{campaign}/resume

A paused run continues; otherwise the campaign is scheduled again.

Key: secretKey · Permissions: campaigns.send

Parameters

  • campaignpathintegerrequired
  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Responses

  • 200OK

    Campaign

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      values: "draft", "scheduled", "sending", "sent", "paused", "cancelled"

    • integration_idinteger | null
    • channelstring | null
    • rate_per_minuteinteger | null
    • next_run_atstring (date-time) | null
    • last_run_atstring (date-time) | null
    • approval_statusstring
      Approval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.

      values: "pending", "approved", "returned"

    • created_atstring (date-time)
    • updated_atstring (date-time)
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Cancel a campaign

post/campaigns/{campaign}/cancel

Unsent recipients of the current run do not get the message; recurring runs stop.

Key: secretKey · Permissions: campaigns.send

Parameters

  • campaignpathintegerrequired
  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Responses

  • 200OK

    Campaign

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      values: "draft", "scheduled", "sending", "sent", "paused", "cancelled"

    • integration_idinteger | null
    • channelstring | null
    • rate_per_minuteinteger | null
    • next_run_atstring (date-time) | null
    • last_run_atstring (date-time) | null
    • approval_statusstring
      Approval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.

      values: "pending", "approved", "returned"

    • created_atstring (date-time)
    • updated_atstring (date-time)
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Submit a campaign for approval

post/campaigns/{campaign}/approval/request

Sends the campaign to review when the project requires approval before launch; approvers get an email. Optional comment.

Key: secretKey · Permissions: campaigns.write

Parameters

  • campaignpathintegerrequired

Request body

  • commentstring

    length: ≤ 1000

Request body example
{
  "comment": "string"
}

Responses

  • 200OK
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Approve a campaign

post/campaigns/{campaign}/approval/approve

Approves a campaign on review. Any later change to the campaign (or, for campaigns, to its templates) sends it back to review.

Key: secretKey · Permissions: campaigns.approve

Parameters

  • campaignpathintegerrequired

Request body

  • commentstring

    length: ≤ 1000

Request body example
{
  "comment": "string"
}

Responses

  • 200OK
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Return a campaign for changes

post/campaigns/{campaign}/approval/return

Sends a campaign on review back to its author; comment is required.

Key: secretKey · Permissions: campaigns.approve

Parameters

  • campaignpathintegerrequired

Request bodyrequired

  • commentstringrequired

    length: ≤ 1000

Request body example
{
  "comment": "string"
}

Responses

  • 200OK
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Chat

Website chat widget settings

get/chat/config

Used by the tracker: whether the chat is enabled, online state (working hours and operators online), color, position, pre-chat form and texts in the visitor language.

Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use /conversations.

Key: writeKey or secretKey

Parameters

  • languagequerystring

    length: ≤ 35

Responses

  • 200Settings; only enabled: false when the chat is off
    • enabledboolean
    • onlineboolean
    • colorstring
    • positionstring

      values: "right", "left"

    • launcherboolean
      Стандартная кнопка чата; false — чат открывает своя кнопка сайта (cdp.openChat() или data-cdp-chat).
    • prechatboolean
    • name_fieldstring
      Имя в анкете: не спрашивать, необязательно, обязательно (обязательное проверяется у первого сообщения нового диалога).

      values: "hidden", "optional", "required"

    • email_fieldstring
      Email в анкете: не спрашивать, необязательно, обязательно.

      values: "hidden", "optional", "required"

    • offline_emailboolean
      Требовать email, когда чат не на связи (проверяет виджет).
    • previewboolean
      Operators see what the visitor is typing: send text with POST /chat/typing (stage 97)
    • textsobject
      • titlestring
      • greetingstring
      • offlinestring
    • departmentsobject[]
      Departments the visitor can choose before the first message (stage 97); the widget shows the choice when there are at least two. online: the department works now (its or the chat's working hours) and one of its operators is online.
      • idinteger
      • namestring
      • onlineboolean
    • filesobject
      Documents the visitor may attach (stage 97)
      • extensionsstring[]
      • max_mbinteger
    • fieldsobject[]
      Pre-chat fields (stage 97) with the label in the visitor language
      • keystring
      • typestring

        values: "text", "phone", "select"

      • requiredboolean
      • optionsstring[]
      • labelstring
    • surveyobject | null
      Post-chat survey (stage 97): questions and texts in the visitor language
      • keystring
      • questionsobject[]
      • textsobject

Messages of the visitor conversation

get/chat/messages

Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use /conversations.

Key: writeKey or secretKey

Parameters

  • conversationquerystring (uuid)required
  • tokenquerystringrequired

    length: ≤ 64

  • afterqueryinteger

    range: ≥ 0

  • readqueryboolean
    Mark operator replies as read by the visitor

    default: true

Responses

Send a visitor message

post/chat/messages

Finds the visitor profile by anonymousId (creates it if needed; userId, name and email go through the same rules as identify with a write key) and adds the message to its open website conversation or starts a new one. An open conversation continues only with its token or from the browser that started it.

Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use /conversations.

Key: writeKey or secretKey

Request bodyrequired

  • anonymousIdstringrequired

    length: ≤ 255

  • userIdstring

    length: ≤ 255

  • userHashstring
    Signature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.

    length: ≤ 128

  • conversationstring (uuid)
    Conversation id from POST /chat/messages
  • tokenstring
    Visitor token of the conversation from POST /chat/messages

    length: ≤ 64

  • bodystring
    Message text. Required unless the message carries images (multipart/form-data).

    length: ≤ 4000

  • namestring

    length: ≤ 100

  • emailstring (email)

    length: ≤ 255

  • pagestring
    Page URL (http/https)

    length: ≤ 2000

  • languagestring

    length: ≤ 35

  • customer_tokenstring
    Token of the customer signed in to the store website, issued by the store (store MCP contract, docs/api/store-mcp.md#5). The store verifies it; the platform stores it encrypted.

    length: ≤ 2000

  • departmentinteger
    Department chosen by the visitor (GET /chat/config → departments) for a new conversation; a department hidden from visitors or of another project is ignored, and the department is then chosen by the page or channel.
  • invitationinteger
    Automatic invitation the visitor replies to (stage 97): its text becomes the first operator message of the new conversation
  • fieldsobject
    Pre-chat fields set in the chat settings (stage 97): field key → value; unknown keys and select values outside the options are dropped
Request body example
{
  "anonymousId": "string",
  "userId": "string",
  "userHash": "string",
  "conversation": "00000000-0000-0000-0000-000000000000",
  "token": "string",
  "body": "string",
  "name": "string",
  "email": "string",
  "page": "string",
  "language": "string",
  "customer_token": "string",
  "department": 0,
  "invitation": 0,
  "fields": {}
}

Responses

  • 201Message stored
  • 403The visitor is blocked (code: blocked)
  • 404The website chat is turned off
  • 409The open conversation of this customer was started in another browser (code `conversation_elsewhere`)
  • 429Too many requests: messages of this browser (20 per minute), new conversations from this IP (5 per minute) or in this project (60 per minute), documents of this browser (20 per hour), or document bytes from this IP (50 MB per hour) or in this project (500 MB per hour); wait for Retry-After seconds

The visitor is typing

post/chat/typing

Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use /conversations. Shares the presence rate limit, separate from event ingestion (ADR-253).

Key: writeKey or secretKey

Request bodyrequired

  • conversationstring (uuid)required
    Conversation id from POST /chat/messages
  • tokenstringrequired
    Visitor token of the conversation from POST /chat/messages

    length: ≤ 64

  • textstring | null
    Text the visitor is still typing (stage 97), sent when the chat config has preview: true. Operators see the first 500 characters; it is not stored.

    length: ≤ 4000

Request body example
{
  "conversation": "00000000-0000-0000-0000-000000000000",
  "token": "string",
  "text": "string"
}

Responses

  • 200Shown to operators of the open conversation
  • 403The visitor of this conversation is blocked (code: blocked)
  • 404Unknown conversation or wrong token

The visitor is on the site

post/chat/presence

Used by the website chat widget of the tracker while the page is visible, at the interval returned in next (stage 97, ADR-244, ADR-253); has its own rate limit, separate from event ingestion; not part of the SDKs.

Key: writeKey or secretKey

Request bodyrequired

  • anonymousIdstringrequired

    length: ≤ 255

  • pagestring
    Current page URL (http or https). Only the path and utm_* parameters are kept: the fragment and other parameters are dropped

    length: ≤ 2000

  • titlestring

    length: ≤ 300

  • referrerstring
    Site the visit came from; only its scheme and host are kept

    length: ≤ 2000

  • sourcestring
    utm_source of the first page or the referring host

    length: ≤ 100

  • started_atinteger
    Start of the visit, Unix time in milliseconds
  • pagesinteger
    Pages viewed in the visit

    range: ≥ 1

  • languagestring

    length: ≤ 35

  • conversationstring (uuid)
    Conversation the widget already knows
  • invitationsboolean
    Return the automatic invitations for this visitor
Request body example
{
  "anonymousId": "string",
  "page": "string",
  "title": "string",
  "referrer": "string",
  "source": "string",
  "started_at": 0,
  "pages": 1,
  "language": "string",
  "conversation": "00000000-0000-0000-0000-000000000000",
  "invitations": true
}

Responses

  • 200The visitor is shown to operators as online for 90 seconds
    • nextinteger
      Seconds until the next presence call: 30 while operators are online or the visitor list is open, 180 otherwise (ADR-253)
    • invitationsobject[]
      Enabled invitations for the visitor segments, text in the visitor language; the widget checks the page rules (stage 97)
      • idinteger
      • textstring
      • senderstring | null
      • rulesobject
    • conversationChatVisitorConversation
      Conversation an operator started with this browser; contains the visitor token

      All fields of ChatVisitorConversation

  • 403The visitor is blocked (code: blocked)
  • 404The chat is disabled
  • 429Too many requests: presence calls of this browser or new browsers from this IP; wait for Retry-After seconds

Answer the post-chat survey

post/chat/survey

Used by the website chat widget after the conversation is rated (stage 97, ADR-246); not part of the SDKs.

Key: writeKey or secretKey

Request bodyrequired

  • conversationstring (uuid)required
  • tokenstringrequired

    length: ≤ 64

  • answersobjectrequired
    Question id → answer (scale number, option or list of options, text)
  • languagestring

    length: ≤ 35

Request body example
{
  "conversation": "00000000-0000-0000-0000-000000000000",
  "token": "string",
  "answers": {},
  "language": "string"
}

Responses

  • 200Recorded; a repeated answer updates the same survey response
  • 403The visitor of this conversation is blocked (code: blocked)
  • 404Unknown conversation, wrong token or no active post-chat survey
  • 422The answers do not fit the questions
  • 429More than 5 calls per hour for this conversation

Rate the conversation

post/chat/rating

Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use /conversations.

Key: writeKey or secretKey

Request bodyrequired

  • conversationstring (uuid)required
    Conversation id from POST /chat/messages
  • tokenstringrequired
    Visitor token of the conversation from POST /chat/messages

    length: ≤ 64

  • ratingintegerrequired

    range: 1–5

  • commentstring

    length: ≤ 1000

Request body example
{
  "conversation": "00000000-0000-0000-0000-000000000000",
  "token": "string",
  "rating": 1,
  "comment": "string"
}

Responses

  • 200Rating stored
  • 403The visitor of this conversation is blocked (code: blocked)
  • 404Unknown conversation or wrong token
  • 422The conversation has never been closed (code rating_open), or the rating is not 1–5
  • 429More than 5 calls per hour for this conversation

Ask for a human operator

post/chat/handoff

The bot (AI in the chat) hands the conversation over to the queue of human operators. Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use /conversations.

Key: writeKey or secretKey

Request bodyrequired

  • conversationstring (uuid)required
    Conversation id from POST /chat/messages
  • tokenstringrequired
    Visitor token of the conversation from POST /chat/messages

    length: ≤ 64

Request body example
{
  "conversation": "00000000-0000-0000-0000-000000000000",
  "token": "string"
}

Responses

  • 200The bot handed the conversation over to the operators
  • 403The visitor of this conversation is blocked (code: blocked)
  • 404Unknown conversation or wrong token

Realtime tokens of the visitor conversation

post/chat/realtime

Centrifugo connection token (anonymous) and subscription token for the channel of this conversation only.

Used by the website chat widget of the tracker; not part of the SDKs. To read and answer conversations from a server, use /conversations.

Key: writeKey or secretKey

Request bodyrequired

  • conversationstring (uuid)required
    Conversation id from POST /chat/messages
  • tokenstringrequired
    Visitor token of the conversation from POST /chat/messages

    length: ≤ 64

Request body example
{
  "conversation": "00000000-0000-0000-0000-000000000000",
  "token": "string"
}

Responses

  • 200Tokens
    • urlstring
    • channelstring
    • connection_tokenstring
    • subscription_tokenstring
  • 403The visitor of this conversation is blocked (code: blocked)
  • 404Unknown conversation or wrong token

Analytics

Run an event report

post/analytics/reports

Report builder: series of an event and a metric (count, unique profiles, per profile, sum or average of a numeric property) with property filters, profile filter, breakdown, interval, period and comparison with the previous period (docs/architecture/analytics.md#конструктор-отчётов). Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Key: secretKey · Permissions: analytics.read

Request bodyrequired

ReportQuery

Request body example
{
  "series": [
    {
      "event": "string",
      "metric": "count",
      "property": "string",
      "filters": [
        {
          "key": "string",
          "operator": "string",
          "value": null
        }
      ]
    }
  ],
  "profiles": {},
  "breakdown": {
    "source": "property",
    "key": "string",
    "limit": 10
  },
  "interval": "day",
  "period": {
    "last": 7
  },
  "compare": true
}

Responses

  • 200OK

    ReportResult

    • definitionobjectrequired
      Normalized definition
    • periodobjectrequired
      • fromstring (date)
      • tostring (date)
    • bucketsstring (date)[]required
    • seriesobject[]required
      Per series: index, total, values per bucket, previous period, breakdown
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Run a funnel

post/analytics/funnels

Steps of events with property filters, conversion window, order, profile filter, breakdown by the first step; conversion and time between steps. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Key: secretKey · Permissions: analytics.read

Request bodyrequired

FunnelQuery

  • stepsobject[]required

    items: 2–10

  • windowobject
    Conversion window from the first step, up to 90 days
    • amountinteger

      range: ≥ 1

    • unitstring

      values: "minute", "hour", "day"

  • orderstring

    values: "sequential", "strict"

  • profilesProfileRules
  • breakdownBreakdown
Request body example
{
  "steps": [
    {
      "event": "string",
      "filters": [
        {
          "key": "string",
          "operator": "string",
          "value": null
        }
      ]
    }
  ],
  "window": {
    "amount": 1,
    "unit": "minute"
  },
  "order": "sequential",
  "profiles": {},
  "breakdown": {
    "source": "property",
    "key": "string",
    "limit": 10
  },
  "period": {
    "last": 7
  }
}

Responses

  • 200OK

    FunnelResult

    • definitionobjectrequired
      Normalized definition
    • periodobjectrequired
      • fromstring (date)
      • tostring (date)
    • stepsobject[]required
      Per step: event, reached, from_start, from_previous, median_seconds, avg_seconds
    • breakdownobject[]required
      Per breakdown value: value, steps (reached per step)
    • time_samplenumber
      Share of profiles used for time between steps
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Run a retention report

post/analytics/retention

Cohorts by the first start event and returns by the return event per day, week or month. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Key: secretKey · Permissions: analytics.read

Request bodyrequired

RetentionQuery

Request body example
{
  "start": {
    "event": "string",
    "filters": [
      {
        "key": "string",
        "operator": "string",
        "value": null
      }
    ]
  },
  "return": {
    "event": "string",
    "filters": [
      {
        "key": "string",
        "operator": "string",
        "value": null
      }
    ]
  },
  "cohort": "first",
  "interval": "day",
  "periods": 1,
  "returns": "exact",
  "profiles": {},
  "period": {
    "last": 7
  }
}

Responses

  • 200OK

    RetentionResult

    • definitionobjectrequired
      Normalized definition
    • periodobjectrequired
      • fromstring (date)
      • tostring (date)
    • cohortsobject[]required
      Per cohort: date, size, values (returned per period, null — not yet), open (period still running)
    • averageobject[]required
      Per period: period, rate, profiles
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Run a paths report

post/analytics/paths

Frequent event sequences after or before the anchor event; nodes and links for a Sankey diagram and the most frequent paths. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Key: secretKey · Permissions: analytics.read

Request bodyrequired

PathQuery

Request body example
{
  "event": "string",
  "filters": [
    {
      "key": "string",
      "operator": "string",
      "value": null
    }
  ],
  "direction": "after",
  "steps": 1,
  "gap_minutes": 1,
  "exclude": [
    "string"
  ],
  "profiles": {},
  "period": {
    "last": 7
  }
}

Responses

  • 200OK

    PathResult

    • definitionobjectrequired
      Normalized definition
    • periodobjectrequired
      • fromstring (date)
      • tostring (date)
    • totalintegerrequired
    • nodesobject[]required
    • linksobject[]required
    • pathsobject[]required
      Most frequent paths: events, profiles
    • truncatedboolean
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Run a revenue report

post/analytics/revenue

Revenue, orders, average order value, new and returning buyers, LTV by first purchase cohort, top products and categories in the project currency. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Key: secretKey · Permissions: analytics.read

Request bodyrequired

RevenueQuery

  • eventstring
    Purchase event; by default from the prediction settings
  • amountstring
    Numeric order amount property
  • product_propertystring
  • ltv_intervalstring

    values: "week", "month"

  • ltv_periodsinteger

    range: 1–12

  • profilesProfileRules
Request body example
{
  "event": "string",
  "amount": "string",
  "product_property": "string",
  "interval": "day",
  "ltv_interval": "week",
  "ltv_periods": 1,
  "profiles": {},
  "period": {
    "last": 7
  }
}

Responses

  • 200OK

    RevenueResult

    • definitionobjectrequired
      Normalized definition
    • periodobjectrequired
      • fromstring (date)
      • tostring (date)
    • currencystring | null
    • other_currency_ordersinteger
    • summaryobjectrequired
    • seriesobjectrequired
    • ltvobjectrequired
    • productsobject[]required
    • categoriesobject[]required
  • 401Missing, invalid or revoked key · Error
  • 402Revenue, traffic, attribution and ROPO reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Run a traffic sources report

post/analytics/traffic

Website visits by channel, source, campaign, referring site or landing page with new profiles, bounces, conversions and revenue. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Key: secretKey · Permissions: analytics.read

Request bodyrequired

TrafficQuery

Request body example
{
  "dimension": "channel",
  "interval": "day",
  "event": "string",
  "amount": "string",
  "profiles": {},
  "period": {
    "last": 7
  }
}

Responses

  • 200OK

    TrafficResult

    • definitionobjectrequired
      Normalized definition
    • periodobjectrequired
      • fromstring (date)
      • tostring (date)
    • currencystring | null
    • purchasesboolean
    • summaryobjectrequired
    • rowsobject[]required
    • row_countinteger
    • chartobjectrequired
  • 401Missing, invalid or revoked key · Error
  • 402Revenue, traffic, attribution and ROPO reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Run a revenue attribution report

post/analytics/attribution

Revenue attributed to platform clicks (campaigns, journeys, messages, recommendations, search) by the last click, first click and linear models. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Key: secretKey · Permissions: analytics.read

Request bodyrequired

AttributionQuery

Request body example
{
  "window_days": 1,
  "model": "last",
  "interval": "day",
  "event": "string",
  "amount": "string",
  "profiles": {},
  "period": {
    "last": 7
  }
}

Responses

  • 200OK

    AttributionResult

    • definitionobjectrequired
      Normalized definition
    • periodobjectrequired
      • fromstring (date)
      • tostring (date)
    • currencystring | null
    • summaryobjectrequired
    • channelsobject[]required
      Per channel: channel, clicks, touched_orders, revenue and orders by model
    • itemsobject[]required
      Per campaign, journey, message channel or widget
    • chartobject
  • 401Missing, invalid or revoked key · Error
  • 402Revenue, traffic, attribution and ROPO reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Run a ROPO report (research online, purchase offline)

post/analytics/ropo

In-store purchases (the offline purchase rule of the project, see /stores) preceded by an online touch of the same customer within the window: website visits by traffic channel, product views, message clicks; customers with and without online touches, touch sources, stores, products viewed online and bought in store, days to purchase and reverse ROPO (online orders after an in-store purchase). Small projects are calculated right away (results cached for 5 minutes). A project with more than 5 million events in the period plus the window is calculated in the queue: the response is 202 with pending: true and Retry-After — repeat the same request. Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Key: secretKey · Permissions: analytics.read

Request bodyrequired

RopoQuery

  • window_daysinteger
    Online touches no earlier than this many days before the in-store check (default 30)

    values: 1, 3, 7, 14, 30, 60, 90

  • touchesstring[]
    Kinds of online touches: website visit (source — traffic channel), product view, message click (default — all)
  • eventstring
    Purchase event (default — from the project settings)
  • amountstring
    Numeric amount property of the purchase event
  • product_propertystring
    Product id property in products[] lines (default — from the recommendation settings)
  • profilesProfileRules
Request body example
{
  "window_days": 1,
  "touches": [
    "visit"
  ],
  "interval": "day",
  "event": "string",
  "amount": "string",
  "product_property": "string",
  "profiles": {},
  "period": {
    "last": 7
  }
}

Responses

  • 200OK

    RopoResult

    • definitionobjectrequired
      Normalized definition
    • pendingboolean
      Only in a 202 response: the report of a large project is being calculated in the queue — repeat the request later
    • periodobject
      • fromstring (date)
      • tostring (date)
    • currencystring | null
    • window_daysinteger
    • touchesstring[]
    • product_viewsboolean
      The project has a product view event: products are matched to views
    • summaryobject
      offline_revenue, offline_orders, offline_buyers, ropo_revenue, ropo_orders, ropo_buyers, ropo_share, ropo_orders_share, online_revenue, online_orders, median_days
    • comparisonobject
      ropo and offline_only customers: buyers, orders, revenue, aov, orders_per_buyer, revenue_per_buyer
    • reverseobject
      Online orders after an in-store purchase within the window (showrooming): online_orders, online_revenue, orders, revenue, buyers, share
    • sourcesobject[]
      Per touch source: kind (visit or message), channel, orders, revenue, buyers, share. A check counts towards every source in its window
    • storesobject[]
      Per store: id, name, city, orders, revenue, buyers, ropo_orders, ropo_revenue, ropo_share, aov, ropo_aov, other_aov, showroom_orders, showroom_revenue
    • productsobject[]
      Products viewed online and bought in store (top 20): id, name, orders, viewed_orders, viewed_share
    • daysobject[]
      Checks with a touch by days from the first touch: from, to, orders, revenue
    • chartobject
      buckets, ropo_revenue, other_offline_revenue, showroom_revenue
  • 202The report is being calculated in the queue: repeat the request after Retry-After seconds

    RopoResult

    • definitionobjectrequired
      Normalized definition
    • pendingboolean
      Only in a 202 response: the report of a large project is being calculated in the queue — repeat the request later
    • periodobject
      • fromstring (date)
      • tostring (date)
    • currencystring | null
    • window_daysinteger
    • touchesstring[]
    • product_viewsboolean
      The project has a product view event: products are matched to views
    • summaryobject
      offline_revenue, offline_orders, offline_buyers, ropo_revenue, ropo_orders, ropo_buyers, ropo_share, ropo_orders_share, online_revenue, online_orders, median_days
    • comparisonobject
      ropo and offline_only customers: buyers, orders, revenue, aov, orders_per_buyer, revenue_per_buyer
    • reverseobject
      Online orders after an in-store purchase within the window (showrooming): online_orders, online_revenue, orders, revenue, buyers, share
    • sourcesobject[]
      Per touch source: kind (visit or message), channel, orders, revenue, buyers, share. A check counts towards every source in its window
    • storesobject[]
      Per store: id, name, city, orders, revenue, buyers, ropo_orders, ropo_revenue, ropo_share, aov, ropo_aov, other_aov, showroom_orders, showroom_revenue
    • productsobject[]
      Products viewed online and bought in store (top 20): id, name, orders, viewed_orders, viewed_share
    • daysobject[]
      Checks with a touch by days from the first touch: from, to, orders, revenue
    • chartobject
      buckets, ropo_revenue, other_offline_revenue, showroom_revenue
  • 401Missing, invalid or revoked key · Error
  • 402Revenue, traffic, attribution and ROPO reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error
  • 503The queued calculation failed; the next request starts it again

Run an AI assistants report

post/analytics/assistants

Shoppers' AI assistants (ChatGPT, Claude, Perplexity …) using the store MCP of the project: requests, product link clicks, carts, orders placed through the store MCP, website visits from their links (utm_medium=ai_assistant), purchases (orders tagged with the assistant by the store module, or a purchase within 30 days after the last visit from an assistant), frequent search queries and popular products. Results are cached for 5 minutes. Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Key: secretKey · Permissions: analytics.read

Request bodyrequired

AssistantsQuery

  • eventstring
    Purchase event; defaults to the purchase event of the project settings. Without it the report has no purchases
  • amountstring
    Numeric property with the order amount
Request body example
{
  "interval": "day",
  "event": "string",
  "amount": "string",
  "period": {
    "last": 7
  }
}

Responses

  • 200OK

    AssistantsResult

    • definitionobjectrequired
      Normalized definition
    • periodobjectrequired
      • fromstring (date)
      • tostring (date)
    • currencystring | null
    • purchasesboolean
    • attribution_daysinteger
    • summaryobjectrequired
      current and previous period: requests, searches, product_clicks, carts, cart_clicks, assistant_orders, visits, visitors, orders, revenue
    • assistantsobject[]required
    • chartobjectrequired
      buckets and per assistant requests and visits by bucket
    • queriesobject[]required
      • querystring
      • countinteger
      • emptyinteger
        Searches without results
    • productsobject[]required
      • idstring
      • namestring | null
      • requestsinteger
      • clicksinteger
  • 401Missing, invalid or revoked key · Error
  • 402AI assistants are not in the plan of the project (code feature_unavailable, feature ai_shopping)
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

List saved reports

get/analytics/saved-reports

Key: secretKey · Permissions: analytics.read

Parameters

Responses

  • 200OK
    • dataSavedReport[]required
    • next_cursorstring | nullrequired
      Pass as cursor to get the next page; null on the last page.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 429Rate limit or monthly event quota exceeded · Error

Save a report

post/analytics/saved-reports

The definition is validated and normalized by the report type; errors come with definition.* paths.

Key: secretKey · Permissions: analytics.write

Parameters

  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

SavedReportInput

  • namestringrequired

    length: ≤ 120

  • definitionobjectrequired
    Definition of the report type — see the run operations
  • viewobject
Request body example
{
  "name": "string",
  "type": "report",
  "definition": {},
  "view": {}
}

Responses

  • 201Created

    SavedReportDetail

    All fields of SavedReport:

    • definitionobjectrequired
    • viewobjectrequired
      Page view settings: chart type, metric
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Get a saved report

get/analytics/saved-reports/{report}

Key: secretKey · Permissions: analytics.read

Parameters

  • reportpathintegerrequired

Responses

  • 200OK

    SavedReportDetail

    All fields of SavedReport:

    • definitionobjectrequired
    • viewobjectrequired
      Page view settings: chart type, metric
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Update a saved report

patch/analytics/saved-reports/{report}

The report type cannot be changed.

Key: secretKey · Permissions: analytics.write

Parameters

  • reportpathintegerrequired

Request bodyrequired

SavedReportPatch

  • namestring

    length: ≤ 120

  • definitionobject
  • viewobject
Request body example
{
  "name": "string",
  "definition": {},
  "view": {}
}

Responses

  • 200OK

    SavedReportDetail

    All fields of SavedReport:

    • definitionobjectrequired
    • viewobjectrequired
      Page view settings: chart type, metric
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Delete a saved report

delete/analytics/saved-reports/{report}

Its cards are removed from dashboards; its email schedules are deleted.

Key: secretKey · Permissions: analytics.write

Parameters

  • reportpathintegerrequired

Responses

  • 204Deleted
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Run a saved report

post/analytics/saved-reports/{report}/result

Optional period replaces the period of the saved definition. Runs the report in ClickHouse (up to 30 s; results cached for 5 minutes). Rate limit: 30 report calculations per minute per key, separate from the general API limit. The response holds the normalized definition and the result — the same as the analytics pages.

Key: secretKey · Permissions: analytics.read

Parameters

  • reportpathintegerrequired

Request bodyrequired

Request body example
{
  "period": {
    "last": 7
  }
}

Responses

  • 200OK

    An object with arbitrary keys.

  • 202A ROPO report of a large project is being calculated in the queue (`pending: true`): repeat the request after Retry-After seconds
  • 401Missing, invalid or revoked key · Error
  • 402Revenue, traffic, attribution and ROPO reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error
  • 503The queued calculation failed; the next request starts it again

List dashboards

get/analytics/dashboards

Key: secretKey · Permissions: analytics.read

Parameters

  • limitqueryinteger

    default: 50 · range: 1–200

  • cursorquerystring

Responses

  • 200OK
    • dataDashboard[]required
    • next_cursorstring | nullrequired
      Pass as cursor to get the next page; null on the last page.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 429Rate limit or monthly event quota exceeded · Error

Create a dashboard

post/analytics/dashboards

Key: secretKey · Permissions: analytics.write

Parameters

  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

DashboardInput

  • namestringrequired

    length: ≤ 120

  • layoutobject[]

    items: ≤ 24

    • report_idintegerrequired
    • sizestring

      values: "half", "full"

  • mainboolean
    true makes the dashboard main (the previous main dashboard stops being main). The flag cannot be cleared: make another dashboard main instead.
Request body example
{
  "name": "string",
  "layout": [
    {
      "report_id": 0,
      "size": "half"
    }
  ],
  "period": {
    "last": 7
  },
  "main": true
}

Responses

  • 201Created

    Dashboard

    • idintegerrequired
    • namestringrequired
    • layoutobject[]required

      items: ≤ 24

      • report_idintegerrequired
      • sizestring

        values: "half", "full"

    • periodAnalyticsPeriodrequired
    • mainbooleanrequired
      The main dashboard of the project: the Dashboards section opens it. A project has one main dashboard; the first dashboard created becomes main.
    • created_atstring (date-time)required
    • updated_atstring (date-time)required
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Get a dashboard

get/analytics/dashboards/{dashboard}

Key: secretKey · Permissions: analytics.read

Parameters

  • dashboardpathintegerrequired

Responses

  • 200OK

    Dashboard

    • idintegerrequired
    • namestringrequired
    • layoutobject[]required

      items: ≤ 24

      • report_idintegerrequired
      • sizestring

        values: "half", "full"

    • periodAnalyticsPeriodrequired
    • mainbooleanrequired
      The main dashboard of the project: the Dashboards section opens it. A project has one main dashboard; the first dashboard created becomes main.
    • created_atstring (date-time)required
    • updated_atstring (date-time)required
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Update a dashboard

patch/analytics/dashboards/{dashboard}

Fields not sent stay unchanged; layout replaces the whole layout.

Key: secretKey · Permissions: analytics.write

Parameters

  • dashboardpathintegerrequired

Request bodyrequired

DashboardPatch

  • namestring

    length: ≤ 120

  • layoutobject[]

    items: ≤ 24

    • report_idintegerrequired
    • sizestring

      values: "half", "full"

  • mainboolean
    true makes the dashboard main (the previous main dashboard stops being main). The flag cannot be cleared: make another dashboard main instead.
Request body example
{
  "name": "string",
  "layout": [
    {
      "report_id": 0,
      "size": "half"
    }
  ],
  "period": {
    "last": 7
  },
  "main": true
}

Responses

  • 200OK

    Dashboard

    • idintegerrequired
    • namestringrequired
    • layoutobject[]required

      items: ≤ 24

      • report_idintegerrequired
      • sizestring

        values: "half", "full"

    • periodAnalyticsPeriodrequired
    • mainbooleanrequired
      The main dashboard of the project: the Dashboards section opens it. A project has one main dashboard; the first dashboard created becomes main.
    • created_atstring (date-time)required
    • updated_atstring (date-time)required
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Delete a dashboard

delete/analytics/dashboards/{dashboard}

Saved reports stay; email schedules of the dashboard are deleted.

Key: secretKey · Permissions: analytics.write

Parameters

  • dashboardpathintegerrequired

Responses

  • 204Deleted
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

List periods of the global control group

get/control-group/periods

Newest first; the active period has ended_at: null. The control group is turned on, resized and turned off only in the project settings, not through the API.

Key: secretKey · Permissions: analytics.read

Parameters

  • limitqueryinteger

    default: 50 · range: 1–200

  • cursorquerystring

Responses

  • 200OK
    • next_cursorstring | nullrequired
      Pass as cursor to get the next page; null on the last page.
  • 401Missing, invalid or revoked key · Error
  • 402The control group is not in the plan of the project (code feature_unavailable, feature control_group)
  • 403The key lacks the required permission or the brand is suspended · Error
  • 429Rate limit or monthly event quota exceeded · Error

Effect of communications by the control group period

get/control-group/periods/{period}/report

Purchases of the control group (profiles that receive no marketing messages) against everyone else during the period: conversion, revenue per profile with significance, incremental revenue, orders and buyers, the cumulative series. Purchases — the purchase event and amount from the revenue settings of the project, in the project currency. Results are cached for 5 minutes. Rate limit: 30 report calculations per minute per key, separate from the general API limit.

Key: secretKey · Permissions: analytics.read

Parameters

  • periodpathintegerrequired

Responses

  • 200OK

    ControlGroupReport

    • untilstring (date-time)
      End of the calculation: the end of the period or the next full hour for the active one
    • currencystring | null
    • eventstring
      Purchase event from the revenue settings of the project
    • groupsobject
      control — profiles of the control group, target — everyone else
    • conversionAbStats
    • revenue_per_profileobject | null
      Welch z-test of revenue per profile, target against control; null with fewer than 30 profiles in a group
      • controlnumber
        Mean revenue per profile of the control group
      • treatmentnumber
        Mean revenue per profile of everyone else
      • differencenumber
      • cinumber[]
        95 % interval of the difference

        items: 2–2

      • liftnumber | null
      • p_valuenumber
      • significantboolean
    • incrementalobject
      Effect of the communications: (target per profile − control per profile) × target profiles
      • revenuenumber
      • revenue_cinumber[] | null

        items: 2–2

      • ordersinteger
      • buyersinteger
    • other_currency_ordersinteger
      Orders in another currency, not counted
    • held_messagesinteger
      Marketing messages not sent to the control group in the period
    • seriesobject
      Cumulative incremental revenue by day (by week for periods longer than 120 days)
      • intervalstring

        values: "day", "week"

      • bucketsstring (date)[]
      • incremental_revenuenumber[]
      • controlnumber[]
        Cumulative revenue per profile
      • targetnumber[]
    • exemptobject
      Campaigns and journeys of the period with «send to the control group too»: the effect is understated
      • campaignsobject[]
        • idinteger
        • namestring
      • journeysobject[]
        • idinteger
        • namestring
  • 401Missing, invalid or revoked key · Error
  • 402The control group is not in the plan of the project (code feature_unavailable, feature control_group)
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422The project has no purchase event in the revenue settings (code no_purchase_event)
  • 429Rate limit or monthly event quota exceeded · Error

Loyalty

Calculate points for a cart

post/loyalty/calculate

How many points the profile can use for a cart of amount (at most max_redeem_percent of the amount and the balance), the discount in the project currency and an estimate of points the order will earn at the member's tier (rules are not included — they depend on the order).

Key: secretKey · Permissions: loyalty.read

Request bodyrequired

  • profileLoyaltyProfileRefrequired
  • amountnumberrequired
    Cart amount in the project currency

    range: ≥ 0

Request body example
{
  "profile": {
    "type": "user_id",
    "value": "string"
  },
  "amount": 0
}

Responses

  • 200OK

    LoyaltyCalculation

    • memberboolean
    • balanceinteger
    • tierstring | null
    • max_pointsinteger
    • max_discountnumber
    • earn_pointsinteger
    • point_valuenumber
    • currencystring | null
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Loyalty account of a profile

get/loyalty/profiles/{type}/{value}

Balance, points waiting for the return period, tier, purchase sum of the tier window and the nearest expiry. A profile that has not joined returns member: false.

Key: secretKey · Permissions: loyalty.read

Parameters

  • typepathstringrequired

    values: "user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"

  • valuepathstringrequired
    Normalized like at ingestion (lower-case email, E.164 phone).

Responses

  • 200OK

    LoyaltyAccount

    • memberboolean
    • balanceinteger
      Available points
    • pendinginteger
      Points waiting for the return period
    • tierstring | null
    • tier_spendnumber
    • expiringinteger
      Points expiring within 30 days
    • expires_atstring (date-time) | null
    • enrolled_atstring (date-time) | null
    • referral_codestring | null
      Code of the member for inviting friends.
    • referral_urlstring | null
      Referral link (?ref= on the store page) when referrals are on.
    • referralsobject
      Friends who came with the code, of them rewarded, and points for them.
      • invitedinteger
      • rewardedinteger
      • pointsinteger
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Point history of a profile

get/loyalty/profiles/{type}/{value}/transactions

Ledger operations from the newest: earn, cancel, expire, adjust, redeem (a hold or a redemption), refund (points returned). Cursor pages.

Key: secretKey · Permissions: loyalty.read

Parameters

  • typepathstringrequired

    values: "user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"

  • valuepathstringrequired
    Normalized like at ingestion (lower-case email, E.164 phone).
  • limitqueryinteger

    default: 50 · range: 1–200

  • cursorquerystring

Responses

  • 200OK
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Join the program

post/loyalty/members

Opens an account for an existing profile — for programs with explicit joining (enrollment: explicit). Returns 200 if the profile is already a member.

Key: secretKey · Permissions: loyalty.write

Parameters

  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

Request body example
{
  "profile": {
    "type": "user_id",
    "value": "string"
  }
}

Responses

  • 201Created

    LoyaltyAccount

    • memberboolean
    • balanceinteger
      Available points
    • pendinginteger
      Points waiting for the return period
    • tierstring | null
    • tier_spendnumber
    • expiringinteger
      Points expiring within 30 days
    • expires_atstring (date-time) | null
    • enrolled_atstring (date-time) | null
    • referral_codestring | null
      Code of the member for inviting friends.
    • referral_urlstring | null
      Referral link (?ref= on the store page) when referrals are on.
    • referralsobject
      Friends who came with the code, of them rewarded, and points for them.
      • invitedinteger
      • rewardedinteger
      • pointsinteger
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Apply a friend's referral code

post/loyalty/referrals

For the registration form of a store: the profile came with the code of a member. The referral counts only for a new customer (no orders, not the member themselves); an identified profile joins the program and gets the friend reward at once (points and, if set, a promo code). 201 — counted now, 200 — counted before. 422 on code: referrals off, unknown code, own code, existing customer.

Key: secretKey · Permissions: loyalty.write

Parameters

  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

Request body example
{
  "profile": {
    "type": "user_id",
    "value": "string"
  },
  "code": "string"
}

Responses

  • 200Counted before

    LoyaltyReferral

    • statusstring
      pending — waiting for the friend's first order.

      values: "pending", "rewarded", "expired", "limit", "cancelled"

    • codestring
    • friend_pointsinteger
    • friend_promo_codestring | null
    • rewardedboolean
      The friend has received the reward.
    • expires_atstring (date-time)
      The first order of the friend rewards the member until this moment.
  • 201Counted

    LoyaltyReferral

    • statusstring
      pending — waiting for the friend's first order.

      values: "pending", "rewarded", "expired", "limit", "cancelled"

    • codestring
    • friend_pointsinteger
    • friend_promo_codestring | null
    • rewardedboolean
      The friend has received the reward.
    • expires_atstring (date-time)
      The first order of the friend rewards the member until this moment.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Hold points for a cart

post/loyalty/redemptions

Takes points off the balance (earliest expiring first) and holds them for 30 minutes while the order is placed. A new hold for the same cart_id returns the previous one. With amount, points are limited to the payable share of the cart. Confirm with the order number or cancel; unconfirmed holds return automatically.

Key: secretKey · Permissions: loyalty.write

Parameters

  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

  • profileLoyaltyProfileRefrequired
  • pointsintegerrequired

    range: ≥ 1

  • cart_idstringrequired

    length: ≤ 255

  • amountnumber

    range: ≥ 0

Request body example
{
  "profile": {
    "type": "user_id",
    "value": "string"
  },
  "points": 1,
  "cart_id": "string",
  "amount": 0
}

Responses

  • 201Created

    LoyaltyRedemption

    • idstring
    • statusstring

      values: "held", "confirmed", "cancelled", "expired"

    • pointsinteger
    • returnedinteger
    • discountnumber
    • cart_idstring
    • order_idstring | null
    • held_untilstring (date-time)
    • confirmed_atstring (date-time) | null
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Confirm a redemption

post/loyalty/redemptions/{redemption}/confirm

Binds the held points to the order. Refunds and cancellations of the order (events order_refunded, order_cancelled) return the points proportionally. Repeating with the same order changes nothing; an expired or cancelled hold — 422.

Key: secretKey · Permissions: loyalty.write

Parameters

  • redemptionpathstringrequired
    Redemption id from the hold response.
  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

  • order_idstringrequired

    length: ≤ 255

Request body example
{
  "order_id": "string"
}

Responses

  • 200OK

    LoyaltyRedemption

    • idstring
    • statusstring

      values: "held", "confirmed", "cancelled", "expired"

    • pointsinteger
    • returnedinteger
    • discountnumber
    • cart_idstring
    • order_idstring | null
    • held_untilstring (date-time)
    • confirmed_atstring (date-time) | null
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Cancel a redemption

post/loyalty/redemptions/{redemption}/cancel

Returns the points of a hold or a confirmed redemption to the balance (into their original lots while they have not expired).

Key: secretKey · Permissions: loyalty.write

Parameters

  • redemptionpathstringrequired
    Redemption id from the hold response.

Responses

  • 200OK

    LoyaltyRedemption

    • idstring
    • statusstring

      values: "held", "confirmed", "cancelled", "expired"

    • pointsinteger
    • returnedinteger
    • discountnumber
    • cart_idstring
    • order_idstring | null
    • held_untilstring (date-time)
    • confirmed_atstring (date-time) | null
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Adjust points manually

post/loyalty/adjustments

Adds points (a lot available at once, with the program lifetime) or takes them off the balance (not more than available), with a reason recorded in the history and the audit log. Send Idempotency-Key to make retries safe.

Key: secretKey · Permissions: loyalty.write

Parameters

  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

  • profileLoyaltyProfileRefrequired
  • pointsintegerrequired
    Positive — add, negative — take off
  • reasonstringrequired

    length: ≤ 500

Request body example
{
  "profile": {
    "type": "user_id",
    "value": "string"
  },
  "points": 0,
  "reason": "string"
}

Responses

  • 200OK

    LoyaltyAccount

    • memberboolean
    • balanceinteger
      Available points
    • pendinginteger
      Points waiting for the return period
    • tierstring | null
    • tier_spendnumber
    • expiringinteger
      Points expiring within 30 days
    • expires_atstring (date-time) | null
    • enrolled_atstring (date-time) | null
    • referral_codestring | null
      Code of the member for inviting friends.
    • referral_urlstring | null
      Referral link (?ref= on the store page) when referrals are on.
    • referralsobject
      Friends who came with the code, of them rewarded, and points for them.
      • invitedinteger
      • rewardedinteger
      • pointsinteger
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Promo

List promo code pools

get/promo/pools

Pools of the project with code counts by status, uses and the revenue of orders with codes.

Key: secretKey · Permissions: promo.read

Responses

  • 200OK
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Get a pool

get/promo/pools/{key}

One pool with its statistics.

Key: secretKey · Permissions: promo.read

Parameters

  • keypathstringrequired
    Pool key — the name used in templates: {{ promo_code('summer') }}.

    pattern: ^[a-z0-9_]{1,64}$

Responses

  • 200OK

    PromoPool

    • keystringrequired
    • namestringrequired
    • typestringrequired
      shared — one code for everyone; unique — a separate code for every profile.

      values: "shared", "unique"

    • statusstringrequired

      values: "active", "paused"

    • activebooleanrequired
      Active now: not paused and within the promotion period.
    • discountstring | null
      Discount text for messages, e.g. «−10 %». The discount itself is a coupon rule of the store.
    • starts_atstring (date-time) | null
    • ends_atstring (date-time) | null
      End of the promotion (exclusive).
    • validity_daysinteger | null
      A code is valid for this many days after it is issued (not longer than the promotion).
    • per_profileintegerrequired
      How many codes of the pool one profile can receive.
    • statsobjectrequired
      • totalinteger
      • availableinteger
      • issuedinteger
      • usedinteger
      • usesinteger
      • revenuenumber
        Sum of the orders with codes of the pool.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Codes of a pool (sync)

get/promo/pools/{key}/codes

For store plugins: codes created or changed after the cursor, oldest first. Store next and pass it as since next time; an empty page returns the same cursor. Changes of the last 10 seconds come with the next call.

Key: secretKey · Permissions: promo.read

Parameters

  • keypathstringrequired
    Pool key — the name used in templates: {{ promo_code('summer') }}.

    pattern: ^[a-z0-9_]{1,64}$

  • sincequerystring
    Cursor from the previous response.
  • limitqueryinteger

    default: 500 · range: 1–1000

Responses

  • 200OK
    • nextstring | null
      Cursor for the next call.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Add codes to a pool

post/promo/pools/{key}/codes

Generates count codes (prefix and length of the pool, up to 50 000) or uploads ready codes (up to 100 000, e.g. coupons exported from the store). Codes that already exist in the project are skipped. Only for unique pools.

Key: secretKey · Permissions: promo.write

Parameters

  • keypathstringrequired
    Pool key — the name used in templates: {{ promo_code('summer') }}.

    pattern: ^[a-z0-9_]{1,64}$

  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

  • countinteger

    range: 1–50000

  • codesstring[]

    items: ≤ 100000

Request body example
{
  "count": 1,
  "codes": [
    "string"
  ]
}

Responses

  • 201Created
    • addedinteger
    • skippedinteger
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Issue a code to a profile

post/promo/pools/{key}/issue

A profile with an active code of the pool gets the same code (200); otherwise the next free code is issued (201, event $promo_code_issued). A shared pool returns its code. 409 with reason: inactive (paused or outside the period), limit (the profile received all its codes), exhausted (no free codes).

Key: secretKey · Permissions: promo.write

Parameters

  • keypathstringrequired
    Pool key — the name used in templates: {{ promo_code('summer') }}.

    pattern: ^[a-z0-9_]{1,64}$

  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

Request body example
{
  "profile": {
    "type": "user_id",
    "value": "string"
  }
}

Responses

  • 200Already issued

    PromoCode

    • poolstring
      Pool key.
    • codestringrequired
    • statusstringrequired

      values: "available", "issued", "used", "shared"

    • issued_atstring (date-time) | null
    • expires_atstring (date-time) | null
    • used_atstring (date-time) | null
  • 201Issued

    PromoCode

    • poolstring
      Pool key.
    • codestringrequired
    • statusstringrequired

      values: "available", "issued", "used", "shared"

    • issued_atstring (date-time) | null
    • expires_atstring (date-time) | null
    • used_atstring (date-time) | null
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 409Not issued
    • messagestring
    • reasonstring

      values: "inactive", "limit", "exhausted"

  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Check a code

get/promo/codes/{code}

Pool, status, validity and the number of orders with the code.

Key: secretKey · Permissions: promo.read

Parameters

  • codepathstringrequired
    Promo code, case-insensitive.

    length: ≤ 64

Responses

  • 200OK

    All fields of PromoCode:

    • activeboolean
      Issued (or shared), not used, not expired, the pool is active.
    • usesinteger
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Codes of a profile

get/promo/profiles/{type}/{value}/codes

Codes issued to the profile, newest first (up to 100) — for the customer account of a store.

Key: secretKey · Permissions: promo.read

Parameters

  • typepathstringrequired

    values: "user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"

  • valuepathstringrequired
    Normalized like at ingestion (lower-case email, E.164 phone).

Responses

  • 200OK
    • dataPromoCode[]

      All fields of PromoCode:

      • activeboolean
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Messages

Send one message now

post/messages

Sends one message to one profile right away — an order confirmation, a password reset, a one-time code. The recipient profile is found by identity or created. Repeat the request with the same Idempotency-Key to retry safely: no second message is sent. No more than MESSAGES_API_PER_RECIPIENT_PER_HOUR (20 by default) messages per recipient per hour through the API. Poll GET /messages/{message} for the delivery status. With steps, the message goes as a cascade — poll GET /messages/cascades/{cascade}; the per-recipient limit counts a cascade once; without the cascades plan feature the answer is 402.

Key: secretKey · Permissions: messages.send

Parameters

  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

MessageSendInput

  • identityIdentityRefrequired
    The recipient. A profile with this identity is created if there is none.
  • traitsobject
    Traits written to the profile before sending, available in the template as traits.*.

    keys: ≤ 100

  • template_idinteger
    Message template. A transactional template skips consents, frequency limits and quiet hours, but not hard blocks of the channel (address does not exist, bot blocked); other templates follow all messaging rules.
  • integration_idinteger | null
    Channel integration of the template's channel; may be omitted when the channel has exactly one active integration.
  • dataobject
    Per-message data, available in the template as context.data.* (order number, confirmation code).
  • Cascade (plans with the cascades feature): channels tried in order — the next one when the profile cannot be reached on the previous, or its message was not sent, not delivered or not read within the step time.

    items: 2–5

Request body example
{
  "identity": {
    "type": "user_id",
    "value": "string"
  },
  "traits": {},
  "template_id": 0,
  "integration_id": 0,
  "data": {},
  "steps": [
    {
      "integration_id": 0,
      "template_id": 0,
      "wait_for": "sent",
      "timeout": {
        "amount": 1,
        "unit": "minute"
      }
    }
  ]
}

Responses

  • 202Queued: a message, or a cascade when `steps` are given
  • 401Missing, invalid or revoked key · Error
  • 402The request cannot be applied in the current state · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Send a store email

post/emails

Sends a ready email of an online store — an order confirmation, an invoice, a password reset — through the project's email integration as is, without a template. The email goes to to as a transactional message: no marketing consent or frequency rules, but bounced and complained addresses are blocked. It is counted in the monthly message quota. The answer is fast: when it is not 202 (no email integration, quota exhausted, the service is unavailable), send the email yourself. Repeat the request with the same Idempotency-Key to retry safely. No more than MESSAGES_STORE_EMAILS_PER_RECIPIENT_PER_HOUR (30 by default) store emails per recipient per hour. Order emails (order_* kinds) with order are built from the OneTrace template enabled for the kind, in the customer language; without an enabled template subject and html are required. Poll GET /messages/{message} for the delivery status.

Key: secretKey · Permissions: messages.send

Parameters

  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

StoreEmailInput

  • tostring (email)required
    Recipient address. The profile is found by this email or created.

    length: ≤ 254

  • subjectstring
    Required unless an order template is enabled for kind and order is given.

    length: ≤ 998

  • htmlstring
    Ready HTML of the store email. Sent as is: it is not a template, braces are not processed. Required unless an order template is enabled for kind and order is given.

    length: ≤ 1000000

  • textstring | null
    Plain-text part; built from the HTML when empty.

    length: ≤ 1000000

  • reply_tostring (email) | null
    Overrides the Reply-To of the email integration.
  • from_namestring | null
    Overrides the sender name of the email integration; the sender address is always the integration's.

    length: ≤ 100

  • kindstringrequired
    What the email is: order_placed, order_paid, order_shipped, order_delivered, order_cancelled, order_refunded, account_new, password_reset, email_verification, login_link, login_code, other … Access-link kinds (password_reset, account_new, email_verification, login_link, login_code) go without click tracking, and only the subject is kept after sending. For order_placed, order_paid, order_shipped, order_delivered, order_cancelled, order_refunded with order, an enabled OneTrace template builds the email instead of html (see GET /emails/settings).

    pattern: ^[a-z0-9_]{1,40}$

  • languagestring | null
    Customer language tag: picks the language version of an order template; for history and reports otherwise.

    length: ≤ 20

  • integration_idinteger | null
    Email integration; may be omitted when the project has exactly one active.
  • traitsobject | null
    Profile traits to update before sending (name, phone).
  • attachmentsobject[]
    Up to 5 files, 5 MB in total.

    items: ≤ 5

    • namestringrequired

      length: ≤ 200

    • typestringrequired

      values: "application/pdf", "image/png", "image/jpeg", "image/gif", "text/plain", "text/csv", "text/calendar"

    • contentstring (byte)required
      File contents in base64.
Request body example
{
  "to": "string",
  "subject": "string",
  "html": "string",
  "text": "string",
  "reply_to": "string",
  "from_name": "string",
  "kind": "string",
  "language": "string",
  "integration_id": 0,
  "traits": {},
  "attachments": [
    {
      "name": "string",
      "type": "application/pdf",
      "content": "string"
    }
  ],
  "order": {
    "order_id": "string",
    "number": "string",
    "url": "https://example.com",
    "created_at": "2026-01-01T10:00:00Z",
    "currency": "string",
    "amount": 0,
    "subtotal": 0,
    "discount": 0,
    "shipping": 0,
    "tax": 0,
    "refund_amount": 0,
    "coupon": "string",
    "payment_method": "string",
    "shipping_method": "string",
    "carrier": "string",
    "tracking_number": "string",
    "tracking_url": "https://example.com",
    "estimated_delivery": "2026-01-01",
    "reason": "string",
    "note": "string",
    "payment_instructions": "string",
    "products": [
      {
        "product_id": "string",
        "variant_id": "string",
        "sku": "string",
        "product_name": "string",
        "quantity": 0,
        "price": 0,
        "total": 0,
        "image_url": "https://example.com",
        "url": "https://example.com",
        "options": "string"
      }
    ],
    "shipping_address": {
      "name": "string",
      "company": "string",
      "address1": "string",
      "address2": "string",
      "city": "string",
      "region": "string",
      "postcode": "string",
      "country": "string",
      "phone": "string"
    },
    "billing_address": {
      "name": "string",
      "company": "string",
      "address1": "string",
      "address2": "string",
      "city": "string",
      "region": "string",
      "postcode": "string",
      "country": "string",
      "phone": "string"
    }
  }
}

Responses

  • 202Queued

    StoreEmailStatus

    All fields of MessageStatus:

    • kindstring | null
    • templateboolean
      The email is built from a OneTrace order template.
  • 401Missing, invalid or revoked key · Error
  • 402The request cannot be applied in the current state · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Store email settings

get/emails/settings

What the store plugin should do: relay store emails through OneTrace and which order emails are built from OneTrace templates. Cache for a few minutes.

Key: secretKey · Permissions: messages.send

Responses

  • 200Settings

    StoreEmailSettings

    • relayboolean
      Send all store emails through OneTrace (store emails section).
    • integration_idinteger | null
    • templatesobject
      Order email kinds built from OneTrace templates: the store does not send its own email for them and passes order instead.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error

Get the state of a cascade

get/messages/cascades/{cascade}

Status of a cascade sent with POST /messages and the messages of its steps.

Key: secretKey · Permissions: messages.send

Parameters

  • cascadepathstring (uuid)required
    Cascade id (UUID) from the send response.

Responses

  • 200OK

    CascadeStatus

    • idstring (uuid)
    • statusstring
      reached — a step succeeded; failed — no channel reached the profile.

      values: "running", "reached", "failed"

    • stepinteger
      Current step, from 0.
    • reached_channelstring | null
    • profile_idinteger
    • originstring | null
    • created_atstring (date-time) | null
    • finished_atstring (date-time) | null
    • Messages of the steps tried so far.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Get the status of a message

get/messages/{message}

Status and timestamps of a message sent with POST /messages (or any message of the project by its id).

Key: secretKey · Permissions: messages.send

Parameters

  • messagepathstring (uuid)required
    Message id (UUID) from the send response.

Responses

  • 200OK

    MessageStatus

    • idstring (uuid)
    • statusstring
      queued → sent → delivered; scheduled — waiting (quiet hours, warm-up); skipped — not sent, see reason; failed/bounced — see reason and error.

      values: "queued", "scheduled", "sent", "delivered", "failed", "skipped", "bounced"

    • reasonstring | null
      Why it was skipped or failed: no_recipient, unsubscribed, recipient_blocked, suppressed, frequency_limit, quota_exceeded, feature_unavailable, delivery_failed, recipient_unreachable, undelivered, template_error, integration_unavailable …
    • errorstring | null
    • channelstring
    • template_idinteger | null
    • integration_idinteger | null
    • profile_idinteger
    • transactionalboolean
    • originstring | null
      api for messages sent with messages.send, store for store emails (emails.send).
    • created_atstring (date-time) | null
    • scheduled_forstring (date-time) | null
    • sent_atstring (date-time) | null
    • delivered_atstring (date-time) | null
    • opened_atstring (date-time) | null
    • clicked_atstring (date-time) | null
    • failed_atstring (date-time) | null
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Conversations

List chat conversations

get/conversations

Conversations of the online chat (website and messengers), newest first. Filter by status, channel or customer.

Key: secretKey · Permissions: chats.read

Parameters

  • statusquerystring
    open — waiting for an answer.

    values: "open", "waiting", "closed"

  • channelquerystring

    values: "web", "telegram", "whatsapp", "viber", "max", "vk", "instagram", "messenger", "email"

  • profile_typequerystring
    Identity type of the customer; together with profile_value.

    values: "user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push"

  • profile_valuequerystring
    Identity value of the customer; together with profile_type.

    length: ≤ 255

  • limitqueryinteger

    default: 50 · range: 1–200

  • cursorquerystring

Responses

  • 200OK
    • dataConversation[]required
    • next_cursorstring | nullrequired
      Pass as cursor to get the next page; null on the last page.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Get a conversation with messages

get/conversations/{conversation}

The conversation and its latest messages, oldest first.

Key: secretKey · Permissions: chats.read

Parameters

  • conversationpathstring (uuid)required
    Conversation id (UUID).
  • limitqueryinteger
    How many latest messages to return.

    default: 100 · range: 1–500

Responses

Answer in a conversation

post/conversations/{conversation}/messages

Sends an answer to the customer as the API key: a bot or an external helpdesk. It does not take an operator seat and is signed with the key name in the operator inbox. The website visitor sees it in the chat widget; a messenger answer goes through the messenger integration (WhatsApp allows free text only within 24 hours of the customer's last message). An answer to a closed conversation reopens it unless the customer already has a newer one.

Key: secretKey · Permissions: chats.reply

Parameters

  • conversationpathstring (uuid)required
    Conversation id (UUID).
  • Idempotency-Keyheaderstring
    Repeat-safe retries: same key and body return the stored response (header Idempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.

    length: ≤ 255

Request bodyrequired

  • bodystring
    Plain text of the answer. Optional when products are given (stage 97).

    length: 1–4000

  • buttonsstring[]
    Quick reply buttons (stage 97): the website widget, Telegram and Viber show buttons, WhatsApp up to three buttons of up to 20 characters, other channels a numbered list; a press arrives as the customer message with the label. Need body.

    items: ≤ 10

  • productsstring[]
    Catalog product ids for product cards (stage 97): a card with the image, name, price and link; in messengers — a separate message.

    items: ≤ 4

Request body example
{
  "body": "string",
  "buttons": [
    "string"
  ],
  "products": [
    "string"
  ]
}

Responses

  • 201Created

    ConversationMessage

    • idintegerrequired
    • authorstringrequired
      visitor — the customer; operator — an answer from the inbox or the API; system — assignment, closing and reopening (see action).

      values: "visitor", "operator", "system"

    • viastring | null
      Where an answer or action came from: the operator inbox or the API.

      values: "inbox", "api", null

    • api_keystring | null
      Name of the API key that answered or closed the conversation.
    • bodystringrequired
      Message text; empty for system messages except notes
    • actionstring | null
      Action of a system message; note — an internal note for operators (body is its text), never shown to the customer

      values: "assigned", "unassigned", "routed", "transferred", "closed", "reopened", "bot_handoff", "store_action", "note", null

    • product_idstring | null
      Product the customer asked about with this message, id in the catalog
    • statusstring | null
      Delivery status of an answer sent to a messenger: queued, sent, delivered, failed, skipped, bounced.
    • created_atstring (date-time)required
    • imagesobject[]
      Customer images (stage 85, ADR-179). url is an absolute signed link valid for about 24 hours, only for status ready. pending — an image from a messenger is still being downloaded; failed — it could not be downloaded or is not a JPEG, PNG or WebP picture; expired — deleted after the storage period.
      • idstring (uuid)
      • statusstring

        values: "ready", "pending", "failed", "expired"

      • urlstring (uri) | null
      • widthinteger | null
      • heightinteger | null
    • filesobject[]
      Documents of the message (stage 97); url is valid for 24 hours, the file is downloaded as an attachment. A customer document is first pending (downloading from the messenger) or checking (stored, checked for active content and by the antivirus in the background) without url, then ready or failed; the message.created webhook carries the first state.
      • idstring
      • statusstring

        values: "pending", "checking", "ready", "failed", "expired"

      • namestring
      • mimestring | null
      • sizeinteger | null
      • urlstring | null
    • buttonsstring[]
      Quick reply buttons of the reply (stage 97)
    • productsobject[]
      Product cards of the reply (stage 97)
      • idstring
      • namestring
      • urlstring | null
      • pricenumber | null
      • currencystring | null
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Close a conversation

post/conversations/{conversation}/close

Closes the conversation; the website visitor is asked to rate it. Closing a closed conversation changes nothing.

Key: secretKey · Permissions: chats.reply

Parameters

  • conversationpathstring (uuid)required
    Conversation id (UUID).

Responses

  • 200OK

    Conversation

    • idstring (uuid)required
    • profile_idintegerrequired
    • channelstringrequired
      web — the website chat; messengers need the chat_messengers plan feature.

      values: "web", "telegram", "whatsapp", "viber", "max", "vk", "instagram", "messenger", "email"

    • statusstringrequired
      open — the customer wrote last and waits for an answer; waiting — answered, waiting for the customer; closed.

      values: "open", "waiting", "closed"

    • assignedbooleanrequired
      An operator is responsible for the conversation.
    • unread_countintegerrequired
      Customer messages operators have not read yet.
    • languagestring | null
    • product_idstring | null
      Last product the customer asked about from the site (product question widget or a product page), id in the catalog
    • tagsstring[]
      Tag names from the project tag dictionary, set by operators (stage 97)
    • ratinginteger | null
      Customer rating after the conversation.

      range: 1–5

    • rating_commentstring | null
    • last_message_atstring (date-time) | null
    • last_message_authorstring | null

      values: "visitor", "operator", "system", null

    • first_reply_atstring (date-time) | null
    • created_atstring (date-time)required
    • closed_atstring (date-time) | null
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 429Rate limit or monthly event quota exceeded · Error

Connect the store MCP server to the AI bot

put/chat/store-mcp

A store plugin connects its MCP server (contract: docs/api/store-mcp.md) to the AI bot of the project: the platform checks the contract marker in initialize, reads tools/list and keeps the contract tools the store owner allowed. One server per URL: calling again updates the key and re-reads the tools.

Key: secretKey · Permissions: chats.manage

Request bodyrequired

  • urlstring (uri)required
    HTTPS address of the store MCP server

    length: ≤ 2048

  • keystringrequired
    Bearer key the platform sends to the store

    length: 32–500

  • namestring

    length: ≤ 120

  • platformstring

    values: "woocommerce", "magento", "bitrix", "sdk", "custom"

Request body example
{
  "url": "https://example.com",
  "key": "string",
  "name": "string",
  "platform": "woocommerce"
}

Responses

  • 200Updated

    StoreMcpServer

    • idstring (uuid)
    • urlstring
    • statusstring
      error — see error; the bot works without this server

      values: "pending", "ok", "error"

    • errorstring | null
    • toolsstring[]
      Contract tools the bot may use
    • checked_atstring (date-time) | null
  • 201Connected

    StoreMcpServer

    • idstring (uuid)
    • urlstring
    • statusstring
      error — see error; the bot works without this server

      values: "pending", "ok", "error"

    • errorstring | null
    • toolsstring[]
      Contract tools the bot may use
    • checked_atstring (date-time) | null
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Disconnect the store MCP server

delete/chat/store-mcp

Removes the store MCP server with this URL from the AI bot of the project.

Key: secretKey · Permissions: chats.manage

Request bodyrequired

  • urlstringrequired

    length: ≤ 2048

Request body example
{
  "url": "string"
}

Responses

  • 204Disconnected
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError

Forms

Submit a website form

post/forms/{uid}/submissions

A visitor submits a signup form of the website (popup, flyout, embedded form or bar). With double opt-in the address gets a confirmation email and becomes part of the profile only after the visitor confirms it; otherwise the email or phone, the consent and the promo code of the form are applied at once.

Used by the website forms of the tracker; not part of the SDKs.

Key: writeKey

Parameters

  • uidpathstringrequired
    Form uid from the site code.

    length: ≤ 16

Request bodyrequired

  • anonymousIdstringrequired

    length: ≤ 255

  • userIdstring

    length: ≤ 255

  • userHashstring
    Signature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.

    length: ≤ 128

  • valuesobjectrequired
    Form fields: email, phone, first_name, last_name, birthday (YYYY-MM-DD) and consent (boolean).
  • languagestring

    length: ≤ 35

  • pagestring

    length: ≤ 2000

  • websitestring
    Hidden trap field: must stay empty.
  • variantstring
    A/B variant of the form the visitor saw.

    values: "a", "b", "c", "d"

  • playstring
    Game forms with the play-first order (stage 81): the play token from POST /forms/{uid}/plays. The submission claims that draw; without it the server draws the prize now.

    length: ≤ 32

Request body example
{
  "anonymousId": "string",
  "userId": "string",
  "userHash": "string",
  "values": {},
  "language": "string",
  "page": "string",
  "website": "string",
  "variant": "a",
  "play": "string"
}

Responses

  • 201Accepted
    • statusstringrequired
      pending — waiting for the confirmation link; accepted — applied to the profile.

      values: "pending", "accepted"

    • messagestringrequired
      Text for the visitor in their language.
    • promo_codestring | null
      Promo code of the form (or of the game prize) when the submission is accepted at once.
    • prizeobject | null
      Game forms (stage 81): the prize of the draw. index — the wheel sector or scratch card prize in the order of game.prizes of the form config; null — no prize could be drawn.
      • keystring | null
      • indexinteger | null
      • kindstring

        values: "promo", "text", "none"

      • labelstring
      • textstring
    • playedboolean
      Game forms: this contact or visitor has already played this form, so there is no second prize.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Play a game form

post/forms/{uid}/plays

A visitor spins the wheel or scratches the card of a game form with the play-first order (stage 81, ADR-175). The server draws the prize by the probabilities of the form; the promo code is not revealed — the visitor claims the prize with a submission that carries the play token. One draw per form for a visitor: a repeat returns the same result.

Used by the website forms of the tracker; not part of the SDKs.

Key: writeKey

Parameters

  • uidpathstringrequired
    Form uid from the site code.

    length: ≤ 16

Request bodyrequired

  • anonymousIdstringrequired

    length: ≤ 255

  • userIdstring

    length: ≤ 255

  • userHashstring
    Signature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.

    length: ≤ 128

  • languagestring

    length: ≤ 35

Request body example
{
  "anonymousId": "string",
  "userId": "string",
  "userHash": "string",
  "language": "string"
}

Responses

  • 201Drawn
    • playstring | null
      Token for the submission; null when this draw has already been claimed.
    • prizeobject | nullrequired
      Game forms (stage 81): the prize of the draw. index — the wheel sector or scratch card prize in the order of game.prizes of the form config; null — no prize could be drawn.
      • keystring | null
      • indexinteger | null
      • kindstring

        values: "promo", "text", "none"

      • labelstring
      • textstring
    • playedbooleanrequired
      The draw has already been claimed by a submission of this visitor.
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 404Not found in the key's project · Error
  • 422Validation failed · ValidationError
  • 429Rate limit or monthly event quota exceeded · Error

Active website forms

get/forms

Active signup forms of the project for the tracker: type, fields, design, display rules and the texts in the visitor's language. The tracker loads its forms module only when there is at least one.

Used by the website forms of the tracker; not part of the SDKs.

Key: writeKey

Parameters

  • languagequerystring
    Visitor language (BCP 47).

    length: ≤ 35

  • anonymousIdquerystring
    Visitor id: forms shown to segment members are filtered by the visitor's profile.

    length: ≤ 255

Responses

  • 200OK
    • formsobject[]required
      • uidstring
      • kindstring

        values: "popup", "flyout", "embedded", "bar"

      • double_opt_inboolean
      • settingsobject
      • rulesobject
      • textsobject
  • 401Missing, invalid or revoked key · Error
  • 403The key lacks the required permission or the brand is suspended · Error
  • 429Rate limit or monthly event quota exceeded · Error

Schemas

Error

  • messagestringrequired

ValidationError

  • messagestringrequired
  • errorsobjectrequired

IdentityRef

  • typestringrequired

    values: "user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push", "mobile_push", "wallet_pass"

  • valuestringrequired

    length: ≤ 255

IdentitiesInput

Message

  • typestring

    values: "track", "identify", "page", "screen", "alias"

  • messageIdstring

    length: ≤ 100

  • anonymousIdstring | integer
  • userIdstring | integer
  • userHashstring
    Signature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.

    length: ≤ 128

  • previousIdstring | integer
  • eventstring

    length: ≤ 200

  • namestring
  • propertiesobject
  • traitsobject
  • contextobject
  • consentsobject[]
    identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.

    items: ≤ 20

    • channelstringrequired

      pattern: ^[a-z0-9_]{1,64}$ · example: "email"

    • topicstring
      Subscription topic; the whole channel if omitted.

      pattern: ^[a-z0-9_-]{1,64}$

    • statusstringrequired

      values: "subscribed", "unsubscribed"

  • timestampstring (date-time)

Profile

  • idinteger
  • traitsobject
  • identitiesobject
  • first_seen_atstring (date-time)
  • last_seen_atstring (date-time)

Event

  • event_idstring
  • typestring
  • namestring
  • propertiesobject
  • contextobject
  • occurred_atstring (date-time)

CatalogEvent

  • namestring
  • labelstring | null
  • volumeinteger
  • first_seen_atstring (date-time) | null
  • last_seen_atstring (date-time) | null
  • propertiesobject[]
    • keystring
    • data_typestring

CatalogTrait

  • keystring
  • labelstring | null
  • data_typestring
  • piiboolean
  • systemboolean

Segment

  • idinteger
  • namestring
  • descriptionstring | null
  • typestring

    values: "dynamic", "static"

  • realtimeboolean
  • schedule_minutesinteger | null
  • statusstring

    values: "pending", "computing", "ready", "failed"

  • sizeinteger
  • last_computed_atstring (date-time) | null
  • created_atstring (date-time)
  • updated_atstring (date-time)

SegmentDetail

All fields of Segment:

  • rulesobject | null
    Rule tree: {"op": "and|or", "children": [...]}

SegmentInput

  • namestringrequired

    length: ≤ 120

  • descriptionstring | null
  • typestringrequired

    values: "dynamic", "static"

  • realtimeboolean
  • schedule_minutesinteger

    values: 15, 30, 60, 180, 360, 720, 1440

  • rulesobject

SegmentPatch

  • namestring

    length: ≤ 120

  • descriptionstring | null
  • realtimeboolean
  • schedule_minutesinteger
  • rulesobject

Journey

  • idinteger
  • namestring
  • descriptionstring | null
  • statusstring

    values: "draft", "active", "paused", "archived"

  • versioninteger | null
  • next_run_atstring (date-time) | null
  • approval_statusstring
    Approval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.

    values: "pending", "approved", "returned"

  • created_atstring (date-time)
  • updated_atstring (date-time)

JourneyDetail

All fields of Journey:

  • draftobject
    • graphobject
    • entryobject
  • publishedobject | null
    • graphobject
    • entryobject

JourneyInput

  • namestringrequired

    length: ≤ 120

  • descriptionstring | null
  • graphobject
    • nodesarray

      items: ≤ 200

    • edgesarray

      items: ≤ 400

  • entryobject

JourneyPatch

  • namestring

    length: ≤ 120

  • descriptionstring | null
  • graphobject
  • entryobject

Enrollment

  • idinteger
  • profile_idinteger
  • version_idinteger
  • statusstring
  • current_node_idstring | null
  • exit_reasonstring | null
  • entered_atstring (date-time)
  • finished_atstring (date-time) | null
  • goal_reached_atstring (date-time) | null

EnrollResult

  • enrolledboolean
  • enrollment_idinteger | null
  • profile_idinteger

CampaignAudience

  • segment_idsinteger[]required
    Members of any of these segments get the campaign.

    items: ≤ 10

  • exclude_segment_idsinteger[]
    Members of these segments are excluded.

    items: ≤ 10

  • ignore_control_groupboolean
    Send to the global control group too (ADR-167). By default profiles of the control group get no marketing messages.

CampaignVariant

  • keystringrequired

    pattern: ^[a-z0-9_]{1,32}$

  • template_idinteger | null
    Message template of the campaign channel.
  • percentintegerrequired
    Share of the audience (or of the A/B test share); all variants add up to 100.

    range: 1–100

CampaignAb

A/B: mode: test (default) — test_percent of the audience is split between variants, after wait the rest gets the winner by metric (test_percent and wait required). mode: auto — recurring campaigns only, tariff feature auto_optimize: each run splits the audience by shares learned from previous runs by metric (ADR-171); test_percent and wait are ignored.
  • modestring

    values: "test", "auto" · default: "test"

  • test_percentinteger

    range: 5–50

  • metricstringrequired

    values: "opened", "clicked", "goal"

  • waitobject
    • amountinteger

      range: 1–72

    • unitstring

      values: "hour", "day"

CampaignSchedule

Times are wall-clock in the project time zone; with local_time — in each recipient's timezone trait; with best_time — at each recipient's best hour within 24 hours of the start.
  • typestringrequired

    values: "now", "at", "recurring"

  • atstring
    For at: Y-m-d\TH:i.

    example: "2026-11-01T10:00"

  • repeatstring

    values: "daily", "weekly", "monthly"

  • timestring

    example: "10:00"

  • weekdaysinteger[]
    ISO weekdays for weekly (1 = Monday).
  • day_of_monthinteger

    range: 1–28

  • start_datestring (date) | null
  • end_datestring (date) | null
  • local_timeboolean
  • best_timeboolean
    Send to each recipient at their best_send_hour trait (predictions) within 24 hours of the start; without it — at the project best hour, otherwise right away. Requires predictions in the plan; not combined with local_time.

CampaignGoal

Conversion: the event from the recipient within the window after sending.
  • eventstringrequired
  • withinobjectrequired
    • amountinteger

      range: 1–90

    • unitstring

      values: "hour", "day"

Campaign

  • idinteger
  • namestring
  • descriptionstring | null
  • statusstring

    values: "draft", "scheduled", "sending", "sent", "paused", "cancelled"

  • integration_idinteger | null
  • channelstring | null
  • rate_per_minuteinteger | null
  • next_run_atstring (date-time) | null
  • last_run_atstring (date-time) | null
  • approval_statusstring
    Approval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.

    values: "pending", "approved", "returned"

  • created_atstring (date-time)
  • updated_atstring (date-time)

CampaignInput

CampaignVariantStats

  • queuedinteger
  • sentinteger
  • deliveredinteger
  • openedinteger
  • clickedinteger
  • bouncedinteger
  • failedinteger
  • skippedinteger
  • unsubscribedinteger
  • convertedinteger | null
    Recipients with the goal event in the window; null without a goal.

CampaignRun

  • idinteger
  • statusstring

    values: "preparing", "sending", "testing", "completed", "paused", "cancelled", "failed"

  • scheduled_atstring (date-time)
  • started_atstring (date-time) | null
  • finished_atstring (date-time) | null
  • audience_sizeinteger
    Recipients without the control group.
  • held_outinteger
    Recipients in the global control group: no message was sent to them.
  • controlobject | null
    Recipients of the run in the control group: no message, $message_skipped with reason control_group at the time the message would have been sent; goal conversion within the same window. null — no control group in the run.
    • profilesinteger
    • convertedinteger | null
      null — the campaign has no goal
    • statsAbStats
      Goal conversion: arm control against arm campaign (sent messages)
  • queuedinteger
  • winnerstring | null
  • winner_atstring (date-time) | null
  • errorstring | null
  • auto_pausedobject | null
    Set while the run is paused automatically: the complaint or bounce rate of the run exceeded the limit. After resuming, the rates are counted again from the messages queued after the resume. null — the run was not paused automatically.
    • atstring (date-time)
    • sentinteger
    • complaint_ratenumber
      Percent
    • bounce_ratenumber
      Percent
    • exceededstring[]
    • limitsobject
      • complaint_ratenumber
      • bounce_ratenumber
  • variantsobject
  • metricstring

    values: "opened", "clicked", "goal"

  • statsAbStats
  • ab_resultobject | null
    Test result saved when the A/B winner was picked.
    • metricstring
    • decided_atstring (date-time)
    • statsAbStats
  • languagesobject
    Results per language of the sent template version.

AbStats

Significance of the difference between variants (docs/architecture/analytics.md#значимость-ab); null with one variant.
  • verdictstring

    values: "winner", "no_difference", "insufficient_data"

  • winnerstring | null
    Set only when the best variant is significantly better than every other one.
  • beststring
  • required_per_arminteger | null
  • alphanumber
  • armsobject[]
    • keystring
    • trialsinteger
    • successesinteger
    • ratenumber
    • cinumber[]
      Wilson 95 % interval

      items: 2–2

    • liftnumber | null
      Relative to the first variant
    • p_valuenumber | null
      Holm-adjusted p-value against the best variant
    • probability_bestnumber

ProductCard

  • idstring
  • namestring
  • urlstring | null
  • imagestring | null
    JPEG up to image_width via imgproxy; without imgproxy — a direct link (CDN copy or feed URL).
  • image_originalstring | null
    Direct link: the platform CDN copy if the feed mirrors images, otherwise the feed URL.
  • srcsetobject | null
    Variants for : AVIF and WebP srcset (240–960 px); null without imgproxy.
    • avifstring
    • webpstring
  • pricenumber | null
  • old_pricenumber | null
  • currencystring | null
  • brandstring | null
  • category_idstring | null
  • min_quantityinteger | null
    The product is sold as a set (tires by 4): how many to add to the cart; null — one.
  • ratingnumber | null
    Average score of published reviews; null without reviews.
  • reviews_countinteger
    Number of published reviews.

ProductInput

  • idstringrequired
    Product id on the site: product_id in events.

    length: ≤ 128

  • namestringrequired

    length: ≤ 500

  • urlstring (uri)
  • imagestring (uri)
  • pricenumber

    range: ≥ 0

  • old_pricenumber

    range: ≥ 0

  • currencystring

    length: 3–3

  • availableboolean

    default: true

  • stockinteger
    Units in stock. Used only when "Use stock levels from the API and plugins" is on in the catalog settings of the project: then the stock is saved, zero takes the product off sale, and the "low stock" journey trigger works. Otherwise it is ignored.

    range: ≥ 0

  • category_idsstring[]
    Leaf category first.

    items: ≤ 10

  • brandstring

    length: ≤ 200

  • descriptionstring
    Product description, plain text or HTML (ADR-132). HTML is turned into text and the result is cut to 5000 characters; the AI answers shoppers' questions about the product from it.

    length: ≤ 65535

  • paramsobject
  • translationsobject
    Translations by language (BCP 47 tag → text), ADR-080: name, url and params in that language; they are shown to visitors and in messages of the language. Languages sent before are kept, a new one is added.

    keys: ≤ 20

MessageTemplate

  • idinteger
  • namestring
  • channelstring

    example: "email"

  • topicstring
    Subscription topic the message belongs to.
  • transactionalboolean
  • languagestring
    Main language of content: recipients whose profile language has no version get it.

    length: ≤ 16 · example: "de"

  • contentobject
    Fields of the channel message schema, e.g. subject, html and text for email; string fields are Twig templates.
  • translationsobject
    Other language versions: language tag → content. A recipient gets the version for the language profile trait (exact tag, then the base language, then another variant of it), otherwise content.
  • versioninteger
    Grows when any language version changes.
  • created_atstring (date-time) | null
  • updated_atstring (date-time) | null

MessageTemplateInput

  • namestringrequired

    length: ≤ 120

  • channel_keystringrequired
    Channel of the template; cannot be changed later.
  • topicstring

    default: "marketing" · length: ≤ 64 · pattern: ^[a-z0-9_-]+$

  • transactionalboolean

    default: false

  • languagestring
    Main language of content; the project default language if omitted.

    length: ≤ 16 · example: "de"

  • contentobjectrequired
    Fields of the channel message schema, e.g. subject, html and text for email; string fields are Twig templates.
  • translationsobject
    Other language versions; each is validated like content. Omit to keep the stored versions, pass {} to delete them.

    keys: ≤ 50

AnalyticsReportType

string

values: "report", "funnel", "retention", "paths", "revenue", "traffic", "attribution", "ropo", "assistants"

AnalyticsPeriod

One of:

    • lastintegerrequired
      Last N days including today, in the project timezone

      values: 7, 14, 30, 90, 180, 365

    • fromstring (date)required
    • tostring (date)required
    Dates in the project timezone, up to 731 days

PropertyFilter

  • keystringrequired
    Property key from the event catalog
  • operatorstringrequired
    Operator of the property type, as in segment rules
  • valueany
    Value for the operator; absent for is_set / is_not_set

ProfileRules

Segment rules (docs/architecture/segmentation.md): only events of matching profiles are counted. Null or an empty group — all profiles.

An object with arbitrary keys.

Breakdown

  • sourcestringrequired

    values: "property", "context"

  • keystringrequired
    Event property, or a page field: page.path, page.referrer, campaign.source, campaign.medium, campaign.name, locale
  • limitinteger
    Event reports only: how many values are shown separately, the rest go to $other. Funnels always show 10.

    values: 5, 10 · default: 10

AnalyticsInterval

string

values: "day", "week", "month"

ReportQuery

FunnelQuery

  • stepsobject[]required

    items: 2–10

  • windowobject
    Conversion window from the first step, up to 90 days
    • amountinteger

      range: ≥ 1

    • unitstring

      values: "minute", "hour", "day"

  • orderstring

    values: "sequential", "strict"

  • profilesProfileRules
  • breakdownBreakdown

RetentionQuery

PathQuery

RevenueQuery

  • eventstring
    Purchase event; by default from the prediction settings
  • amountstring
    Numeric order amount property
  • product_propertystring
  • ltv_intervalstring

    values: "week", "month"

  • ltv_periodsinteger

    range: 1–12

  • profilesProfileRules

TrafficQuery

AttributionQuery

ReportResult

  • definitionobjectrequired
    Normalized definition
  • periodobjectrequired
    • fromstring (date)
    • tostring (date)
  • bucketsstring (date)[]required
  • seriesobject[]required
    Per series: index, total, values per bucket, previous period, breakdown

FunnelResult

  • definitionobjectrequired
    Normalized definition
  • periodobjectrequired
    • fromstring (date)
    • tostring (date)
  • stepsobject[]required
    Per step: event, reached, from_start, from_previous, median_seconds, avg_seconds
  • breakdownobject[]required
    Per breakdown value: value, steps (reached per step)
  • time_samplenumber
    Share of profiles used for time between steps

RetentionResult

  • definitionobjectrequired
    Normalized definition
  • periodobjectrequired
    • fromstring (date)
    • tostring (date)
  • cohortsobject[]required
    Per cohort: date, size, values (returned per period, null — not yet), open (period still running)
  • averageobject[]required
    Per period: period, rate, profiles

PathResult

  • definitionobjectrequired
    Normalized definition
  • periodobjectrequired
    • fromstring (date)
    • tostring (date)
  • totalintegerrequired
  • nodesobject[]required
  • linksobject[]required
  • pathsobject[]required
    Most frequent paths: events, profiles
  • truncatedboolean

RevenueResult

  • definitionobjectrequired
    Normalized definition
  • periodobjectrequired
    • fromstring (date)
    • tostring (date)
  • currencystring | null
  • other_currency_ordersinteger
  • summaryobjectrequired
  • seriesobjectrequired
  • ltvobjectrequired
  • productsobject[]required
  • categoriesobject[]required

TrafficResult

  • definitionobjectrequired
    Normalized definition
  • periodobjectrequired
    • fromstring (date)
    • tostring (date)
  • currencystring | null
  • purchasesboolean
  • summaryobjectrequired
  • rowsobject[]required
  • row_countinteger
  • chartobjectrequired

AttributionResult

  • definitionobjectrequired
    Normalized definition
  • periodobjectrequired
    • fromstring (date)
    • tostring (date)
  • currencystring | null
  • summaryobjectrequired
  • channelsobject[]required
    Per channel: channel, clicks, touched_orders, revenue and orders by model
  • itemsobject[]required
    Per campaign, journey, message channel or widget
  • chartobject

SavedReport

  • idintegerrequired
  • namestringrequired
  • created_atstring (date-time)required
  • updated_atstring (date-time)required

SavedReportDetail

All fields of SavedReport:

  • definitionobjectrequired
  • viewobjectrequired
    Page view settings: chart type, metric

SavedReportInput

  • namestringrequired

    length: ≤ 120

  • definitionobjectrequired
    Definition of the report type — see the run operations
  • viewobject

SavedReportPatch

  • namestring

    length: ≤ 120

  • definitionobject
  • viewobject

Dashboard

  • idintegerrequired
  • namestringrequired
  • layoutobject[]required

    items: ≤ 24

    • report_idintegerrequired
    • sizestring

      values: "half", "full"

  • periodAnalyticsPeriodrequired
  • mainbooleanrequired
    The main dashboard of the project: the Dashboards section opens it. A project has one main dashboard; the first dashboard created becomes main.
  • created_atstring (date-time)required
  • updated_atstring (date-time)required

DashboardInput

  • namestringrequired

    length: ≤ 120

  • layoutobject[]

    items: ≤ 24

    • report_idintegerrequired
    • sizestring

      values: "half", "full"

  • mainboolean
    true makes the dashboard main (the previous main dashboard stops being main). The flag cannot be cleared: make another dashboard main instead.

DashboardPatch

  • namestring

    length: ≤ 120

  • layoutobject[]

    items: ≤ 24

    • report_idintegerrequired
    • sizestring

      values: "half", "full"

  • mainboolean
    true makes the dashboard main (the previous main dashboard stops being main). The flag cannot be cleared: make another dashboard main instead.

LoyaltyProfileRef

  • typestringrequired

    values: "user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push"

  • valuestringrequired

LoyaltyAccount

  • memberboolean
  • balanceinteger
    Available points
  • pendinginteger
    Points waiting for the return period
  • tierstring | null
  • tier_spendnumber
  • expiringinteger
    Points expiring within 30 days
  • expires_atstring (date-time) | null
  • enrolled_atstring (date-time) | null
  • referral_codestring | null
    Code of the member for inviting friends.
  • referral_urlstring | null
    Referral link (?ref= on the store page) when referrals are on.
  • referralsobject
    Friends who came with the code, of them rewarded, and points for them.
    • invitedinteger
    • rewardedinteger
    • pointsinteger

LoyaltyCalculation

  • memberboolean
  • balanceinteger
  • tierstring | null
  • max_pointsinteger
  • max_discountnumber
  • earn_pointsinteger
  • point_valuenumber
  • currencystring | null

LoyaltyRedemption

  • idstring
  • statusstring

    values: "held", "confirmed", "cancelled", "expired"

  • pointsinteger
  • returnedinteger
  • discountnumber
  • cart_idstring
  • order_idstring | null
  • held_untilstring (date-time)
  • confirmed_atstring (date-time) | null

LoyaltyTransaction

  • idinteger
  • typestring

    values: "earn", "cancel", "expire", "adjust", "redeem", "refund"

  • pointsinteger
  • referencestring | null
  • reasonstring | null
  • rulestring | null
  • created_atstring (date-time)
  • referralstring | null
    Referral reward: friend — for joining by invitation, referrer — for the first order of a friend.

    values: "friend", "referrer", null

PromoPool

  • keystringrequired
  • namestringrequired
  • typestringrequired
    shared — one code for everyone; unique — a separate code for every profile.

    values: "shared", "unique"

  • statusstringrequired

    values: "active", "paused"

  • activebooleanrequired
    Active now: not paused and within the promotion period.
  • discountstring | null
    Discount text for messages, e.g. «−10 %». The discount itself is a coupon rule of the store.
  • starts_atstring (date-time) | null
  • ends_atstring (date-time) | null
    End of the promotion (exclusive).
  • validity_daysinteger | null
    A code is valid for this many days after it is issued (not longer than the promotion).
  • per_profileintegerrequired
    How many codes of the pool one profile can receive.
  • statsobjectrequired
    • totalinteger
    • availableinteger
    • issuedinteger
    • usedinteger
    • usesinteger
    • revenuenumber
      Sum of the orders with codes of the pool.

PromoCode

  • poolstring
    Pool key.
  • codestringrequired
  • statusstringrequired

    values: "available", "issued", "used", "shared"

  • issued_atstring (date-time) | null
  • expires_atstring (date-time) | null
  • used_atstring (date-time) | null

LoyaltyReferral

  • statusstring
    pending — waiting for the friend's first order.

    values: "pending", "rewarded", "expired", "limit", "cancelled"

  • codestring
  • friend_pointsinteger
  • friend_promo_codestring | null
  • rewardedboolean
    The friend has received the reward.
  • expires_atstring (date-time)
    The first order of the friend rewards the member until this moment.

MessageSendInput

Pass template_id (and integration_id if needed) for one message, or steps for a cascade — not both.
  • identityIdentityRefrequired
    The recipient. A profile with this identity is created if there is none.
  • traitsobject
    Traits written to the profile before sending, available in the template as traits.*.

    keys: ≤ 100

  • template_idinteger
    Message template. A transactional template skips consents, frequency limits and quiet hours, but not hard blocks of the channel (address does not exist, bot blocked); other templates follow all messaging rules.
  • integration_idinteger | null
    Channel integration of the template's channel; may be omitted when the channel has exactly one active integration.
  • dataobject
    Per-message data, available in the template as context.data.* (order number, confirmation code).
  • Cascade (plans with the cascades feature): channels tried in order — the next one when the profile cannot be reached on the previous, or its message was not sent, not delivered or not read within the step time.

    items: 2–5

MessageStatus

  • idstring (uuid)
  • statusstring
    queued → sent → delivered; scheduled — waiting (quiet hours, warm-up); skipped — not sent, see reason; failed/bounced — see reason and error.

    values: "queued", "scheduled", "sent", "delivered", "failed", "skipped", "bounced"

  • reasonstring | null
    Why it was skipped or failed: no_recipient, unsubscribed, recipient_blocked, suppressed, frequency_limit, quota_exceeded, feature_unavailable, delivery_failed, recipient_unreachable, undelivered, template_error, integration_unavailable …
  • errorstring | null
  • channelstring
  • template_idinteger | null
  • integration_idinteger | null
  • profile_idinteger
  • transactionalboolean
  • originstring | null
    api for messages sent with messages.send, store for store emails (emails.send).
  • created_atstring (date-time) | null
  • scheduled_forstring (date-time) | null
  • sent_atstring (date-time) | null
  • delivered_atstring (date-time) | null
  • opened_atstring (date-time) | null
  • clicked_atstring (date-time) | null
  • failed_atstring (date-time) | null

CascadeStep

  • integration_idintegerrequired
  • template_idintegerrequired
    Template of the integration's channel.
  • wait_forstring
    What counts as success. delivered needs an integration that reports delivery (not email through own SMTP), opened — a channel that reports reading (email, WhatsApp, Viber).

    values: "sent", "delivered", "opened" · default: "sent"

  • timeoutobject
    How long to wait for delivered or opened after sending; 15 minutes by default.
    • amountinteger

      range: 1–3650

    • unitstring

      values: "minute", "hour", "day", "week"

CascadeStatus

  • idstring (uuid)
  • statusstring
    reached — a step succeeded; failed — no channel reached the profile.

    values: "running", "reached", "failed"

  • stepinteger
    Current step, from 0.
  • reached_channelstring | null
  • profile_idinteger
  • originstring | null
  • created_atstring (date-time) | null
  • finished_atstring (date-time) | null
  • Messages of the steps tried so far.

ChatVisitorMessage

  • idinteger
  • authorstring

    values: "visitor", "operator", "system"

  • bodystring
  • operatorstring | null
    First name of the operator
  • actionstring | null
    closed — the conversation was closed
  • created_atstring (date-time)
  • botboolean
    Reply of the AI bot; operator holds the bot name
  • imagesobject[]
    Images of the message (stage 85). url is a signed path valid for about 24 hours: prepend the platform host. Without url: status expired (deleted after the storage period, 180 days by default).
    • urlstring | null
    • widthinteger | null
    • heightinteger | null
    • statusstring

      values: "ready", "pending", "failed", "expired"

  • filesobject[]
    Documents of the message (stage 97); url is a signed path valid for about 24 hours: prepend the platform host. The file is downloaded as an attachment. A document of the visitor is first checking (no url) and then ready or failed; the change comes as the realtime event message.updated with the whole message.
    • namestring
    • sizeinteger | null
    • urlstring | null
    • statusstring

      values: "pending", "checking", "ready", "failed", "expired"

    • errorstring | null
      Why a failed document was not accepted: unsafe (macros, scripts, embedded objects or external links), infected (the antivirus found a threat), scan (the antivirus stayed unavailable), type, quota, download
  • buttonsstring[]
    Quick reply buttons of an operator message (stage 97): a press sends the label as the visitor message
  • productsobject[]
    Catalog product cards of an operator message (stage 97)
    • idstring
    • namestring
    • urlstring | null
    • imagestring | null
    • pricenumber | null
    • currencystring | null
    • availableboolean

ChatVisitorConversation

  • idstring (uuid)
  • statusstring

    values: "open", "waiting", "closed"

  • ratinginteger | null
  • tokenstring
    Returned for a new conversation or when the request had no valid token; store it
  • botboolean
    The AI bot leads the conversation: the widget offers to call an operator (POST /chat/handoff)
  • queueinteger | null
    Place in the operators' queue (1 — next) while the conversation waits for an operator with automatic routing; null otherwise

Conversation

  • idstring (uuid)required
  • profile_idintegerrequired
  • channelstringrequired
    web — the website chat; messengers need the chat_messengers plan feature.

    values: "web", "telegram", "whatsapp", "viber", "max", "vk", "instagram", "messenger", "email"

  • statusstringrequired
    open — the customer wrote last and waits for an answer; waiting — answered, waiting for the customer; closed.

    values: "open", "waiting", "closed"

  • assignedbooleanrequired
    An operator is responsible for the conversation.
  • unread_countintegerrequired
    Customer messages operators have not read yet.
  • languagestring | null
  • product_idstring | null
    Last product the customer asked about from the site (product question widget or a product page), id in the catalog
  • tagsstring[]
    Tag names from the project tag dictionary, set by operators (stage 97)
  • ratinginteger | null
    Customer rating after the conversation.

    range: 1–5

  • rating_commentstring | null
  • last_message_atstring (date-time) | null
  • last_message_authorstring | null

    values: "visitor", "operator", "system", null

  • first_reply_atstring (date-time) | null
  • created_atstring (date-time)required
  • closed_atstring (date-time) | null

ConversationMessage

  • idintegerrequired
  • authorstringrequired
    visitor — the customer; operator — an answer from the inbox or the API; system — assignment, closing and reopening (see action).

    values: "visitor", "operator", "system"

  • viastring | null
    Where an answer or action came from: the operator inbox or the API.

    values: "inbox", "api", null

  • api_keystring | null
    Name of the API key that answered or closed the conversation.
  • bodystringrequired
    Message text; empty for system messages except notes
  • actionstring | null
    Action of a system message; note — an internal note for operators (body is its text), never shown to the customer

    values: "assigned", "unassigned", "routed", "transferred", "closed", "reopened", "bot_handoff", "store_action", "note", null

  • product_idstring | null
    Product the customer asked about with this message, id in the catalog
  • statusstring | null
    Delivery status of an answer sent to a messenger: queued, sent, delivered, failed, skipped, bounced.
  • created_atstring (date-time)required
  • imagesobject[]
    Customer images (stage 85, ADR-179). url is an absolute signed link valid for about 24 hours, only for status ready. pending — an image from a messenger is still being downloaded; failed — it could not be downloaded or is not a JPEG, PNG or WebP picture; expired — deleted after the storage period.
    • idstring (uuid)
    • statusstring

      values: "ready", "pending", "failed", "expired"

    • urlstring (uri) | null
    • widthinteger | null
    • heightinteger | null
  • filesobject[]
    Documents of the message (stage 97); url is valid for 24 hours, the file is downloaded as an attachment. A customer document is first pending (downloading from the messenger) or checking (stored, checked for active content and by the antivirus in the background) without url, then ready or failed; the message.created webhook carries the first state.
    • idstring
    • statusstring

      values: "pending", "checking", "ready", "failed", "expired"

    • namestring
    • mimestring | null
    • sizeinteger | null
    • urlstring | null
  • buttonsstring[]
    Quick reply buttons of the reply (stage 97)
  • productsobject[]
    Product cards of the reply (stage 97)
    • idstring
    • namestring
    • urlstring | null
    • pricenumber | null
    • currencystring | null

ConversationDetail

All fields of Conversation:

StoreEmailInput

  • tostring (email)required
    Recipient address. The profile is found by this email or created.

    length: ≤ 254

  • subjectstring
    Required unless an order template is enabled for kind and order is given.

    length: ≤ 998

  • htmlstring
    Ready HTML of the store email. Sent as is: it is not a template, braces are not processed. Required unless an order template is enabled for kind and order is given.

    length: ≤ 1000000

  • textstring | null
    Plain-text part; built from the HTML when empty.

    length: ≤ 1000000

  • reply_tostring (email) | null
    Overrides the Reply-To of the email integration.
  • from_namestring | null
    Overrides the sender name of the email integration; the sender address is always the integration's.

    length: ≤ 100

  • kindstringrequired
    What the email is: order_placed, order_paid, order_shipped, order_delivered, order_cancelled, order_refunded, account_new, password_reset, email_verification, login_link, login_code, other … Access-link kinds (password_reset, account_new, email_verification, login_link, login_code) go without click tracking, and only the subject is kept after sending. For order_placed, order_paid, order_shipped, order_delivered, order_cancelled, order_refunded with order, an enabled OneTrace template builds the email instead of html (see GET /emails/settings).

    pattern: ^[a-z0-9_]{1,40}$

  • languagestring | null
    Customer language tag: picks the language version of an order template; for history and reports otherwise.

    length: ≤ 20

  • integration_idinteger | null
    Email integration; may be omitted when the project has exactly one active.
  • traitsobject | null
    Profile traits to update before sending (name, phone).
  • attachmentsobject[]
    Up to 5 files, 5 MB in total.

    items: ≤ 5

    • namestringrequired

      length: ≤ 200

    • typestringrequired

      values: "application/pdf", "image/png", "image/jpeg", "image/gif", "text/plain", "text/csv", "text/calendar"

    • contentstring (byte)required
      File contents in base64.

StoreEmailStatus

All fields of MessageStatus:

  • kindstring | null
  • templateboolean
    The email is built from a OneTrace order template.

StoreOrder

Order data for order email templates — the order template variable.
  • order_idstringrequired

    length: ≤ 100

  • numberstring | null
    Number shown to the customer; order_id when empty.

    length: ≤ 100

  • urlstring (uri) | null
    Order page for the customer.
  • created_atstring (date-time) | null
  • currencystringrequired

    pattern: ^[A-Za-z]{3}$

  • amountnumberrequired
    Order total.
  • subtotalnumber | null
  • discountnumber | null
  • shippingnumber | null
  • taxnumber | null
  • refund_amountnumber | null
  • couponstring | null
  • payment_methodstring | null
  • shipping_methodstring | null
  • carrierstring | null
  • tracking_numberstring | null
  • tracking_urlstring (uri) | null
  • estimated_deliverystring (date) | null
  • reasonstring | null
    Cancellation or refund reason.
  • notestring | null
  • payment_instructionsstring | null
    Bank transfer details and similar instructions.
  • productsobject[]

    items: ≤ 100

    • product_idstring | null
    • variant_idstring | null
    • skustring | null
    • product_namestringrequired

      length: ≤ 300

    • quantitynumberrequired
    • pricenumberrequired
    • totalnumber | null
      Line total; price × quantity when empty.
    • image_urlstring (uri) | null
    • urlstring (uri) | null
    • optionsstring | null
      Variant options as text: «Size: M, colour: white».

      length: ≤ 500

  • shipping_addressobject | null
    • namestring | null

      length: ≤ 200

    • companystring | null

      length: ≤ 200

    • address1string | null

      length: ≤ 200

    • address2string | null

      length: ≤ 200

    • citystring | null

      length: ≤ 200

    • regionstring | null

      length: ≤ 200

    • postcodestring | null

      length: ≤ 200

    • countrystring | null

      length: ≤ 200

    • phonestring | null

      length: ≤ 200

  • billing_addressobject | null
    • namestring | null

      length: ≤ 200

    • companystring | null

      length: ≤ 200

    • address1string | null

      length: ≤ 200

    • address2string | null

      length: ≤ 200

    • citystring | null

      length: ≤ 200

    • regionstring | null

      length: ≤ 200

    • postcodestring | null

      length: ≤ 200

    • countrystring | null

      length: ≤ 200

    • phonestring | null

      length: ≤ 200

StoreEmailSettings

  • relayboolean
    Send all store emails through OneTrace (store emails section).
  • integration_idinteger | null
  • templatesobject
    Order email kinds built from OneTrace templates: the store does not send its own email for them and passes order instead.

StoreMcpServer

  • idstring (uuid)
  • urlstring
  • statusstring
    error — see error; the bot works without this server

    values: "pending", "ok", "error"

  • errorstring | null
  • toolsstring[]
    Contract tools the bot may use
  • checked_atstring (date-time) | null

ProfilePreferences

Subscription preferences of a profile (preference center): topics by channel, frequency and pause of marketing messages.
  • profile_idinteger
  • languagestring
    Language of topic names.

    example: "en"

  • channelsobject[]
    Channels the profile receives or can receive messages in: channels of its consents and messages of the last year, and channels of active integrations it has an address for.
    • keystring

      example: "email"

    • namestring
      Name of the channel in the requested language, lower case as inside a sentence.

      example: "email"

    • blockedboolean
      Hard block (the address does not exist, the bot was stopped): read only.
  • unsubscribed_allboolean
    The profile unsubscribed from marketing messages in all channels (unsubscribe_all or the preference center): channels without their own subscription stay closed.
  • adsboolean | null
    Advertising consent; null — the project has no ad platform connected, nothing to ask.
  • topicsobject[]
    Visible subscription topics.
    • keystring

      example: "news"

    • namestring
    • descriptionstring
    • channelsobject
      Channel key → subscribed (true/false), null — the topic is not offered in this channel.
  • frequencystring | null
    At most one marketing message per week or month across channels; null — as usual.

    values: "weekly", "monthly", null

  • paused_untilstring (date-time) | null
    Marketing messages are paused until this time.
  • preferences_urlstring (uri)
    Signed link to the preference center page of this profile, valid for 30 days — for a «Manage subscriptions» link in the store account.
  • preferences_url_expires_atstring (date-time)

Store

  • idstringrequired
    Store id — the value of store_id in offline checks.

    length: ≤ 128

  • namestringrequired

    length: ≤ 200

  • citystring | null

    length: ≤ 120

  • addressstring | null

    length: ≤ 300

RopoQuery

  • window_daysinteger
    Online touches no earlier than this many days before the in-store check (default 30)

    values: 1, 3, 7, 14, 30, 60, 90

  • touchesstring[]
    Kinds of online touches: website visit (source — traffic channel), product view, message click (default — all)
  • eventstring
    Purchase event (default — from the project settings)
  • amountstring
    Numeric amount property of the purchase event
  • product_propertystring
    Product id property in products[] lines (default — from the recommendation settings)
  • profilesProfileRules

RopoResult

  • definitionobjectrequired
    Normalized definition
  • pendingboolean
    Only in a 202 response: the report of a large project is being calculated in the queue — repeat the request later
  • periodobject
    • fromstring (date)
    • tostring (date)
  • currencystring | null
  • window_daysinteger
  • touchesstring[]
  • product_viewsboolean
    The project has a product view event: products are matched to views
  • summaryobject
    offline_revenue, offline_orders, offline_buyers, ropo_revenue, ropo_orders, ropo_buyers, ropo_share, ropo_orders_share, online_revenue, online_orders, median_days
  • comparisonobject
    ropo and offline_only customers: buyers, orders, revenue, aov, orders_per_buyer, revenue_per_buyer
  • reverseobject
    Online orders after an in-store purchase within the window (showrooming): online_orders, online_revenue, orders, revenue, buyers, share
  • sourcesobject[]
    Per touch source: kind (visit or message), channel, orders, revenue, buyers, share. A check counts towards every source in its window
  • storesobject[]
    Per store: id, name, city, orders, revenue, buyers, ropo_orders, ropo_revenue, ropo_share, aov, ropo_aov, other_aov, showroom_orders, showroom_revenue
  • productsobject[]
    Products viewed online and bought in store (top 20): id, name, orders, viewed_orders, viewed_share
  • daysobject[]
    Checks with a touch by days from the first touch: from, to, orders, revenue
  • chartobject
    buckets, ropo_revenue, other_offline_revenue, showroom_revenue

ControlGroupPeriod

A period of the global control group: every change of the share starts a new period with a new membership.
  • idinteger
  • percentinteger
    Share of profiles in the control group, %

    range: 1–50

  • started_atstring (date-time)
  • ended_atstring (date-time) | null
    null for the active period

ControlGroupSide

  • profilesinteger
  • buyersinteger
  • ordersinteger
  • revenuenumber
  • conversionnumber | null
    Buyers / profiles
  • revenue_per_profilenumber | null
  • aovnumber | null
    Average order value

ControlGroupReport

  • untilstring (date-time)
    End of the calculation: the end of the period or the next full hour for the active one
  • currencystring | null
  • eventstring
    Purchase event from the revenue settings of the project
  • groupsobject
    control — profiles of the control group, target — everyone else
  • conversionAbStats
  • revenue_per_profileobject | null
    Welch z-test of revenue per profile, target against control; null with fewer than 30 profiles in a group
    • controlnumber
      Mean revenue per profile of the control group
    • treatmentnumber
      Mean revenue per profile of everyone else
    • differencenumber
    • cinumber[]
      95 % interval of the difference

      items: 2–2

    • liftnumber | null
    • p_valuenumber
    • significantboolean
  • incrementalobject
    Effect of the communications: (target per profile − control per profile) × target profiles
    • revenuenumber
    • revenue_cinumber[] | null

      items: 2–2

    • ordersinteger
    • buyersinteger
  • other_currency_ordersinteger
    Orders in another currency, not counted
  • held_messagesinteger
    Marketing messages not sent to the control group in the period
  • seriesobject
    Cumulative incremental revenue by day (by week for periods longer than 120 days)
    • intervalstring

      values: "day", "week"

    • bucketsstring (date)[]
    • incremental_revenuenumber[]
    • controlnumber[]
      Cumulative revenue per profile
    • targetnumber[]
  • exemptobject
    Campaigns and journeys of the period with «send to the control group too»: the effect is understated
    • campaignsobject[]
      • idinteger
      • namestring
    • journeysobject[]
      • idinteger
      • namestring

LaunchReadiness

  • readybooleanrequired
    No errors: the launch will pass.
  • clearbooleanrequired
    No errors and no warnings.
  • checksobject[]required
    • keystringrequired
      config, archived, quota, sending_domain, integration, untranslated, template_error, unsubscribe, deliverability, segment_pending, segment_empty, segment_broad, goal_missing, goal_unseen, goal_window
    • levelstringrequired

      values: "error", "warning", "info"

    • messagestringrequired
      Text in the language of the request
    • pathstring
      Field of a config error, e.g. variants.0.template_id

EventSchema

  • enabledboolean
    Check incoming events against the schema
  • eventsobject[]

    items: ≤ 1000

    • namestringrequired
      Event name (system $… events are not allowed)

      length: ≤ 255

    • labelstring | null

      length: ≤ 255

    • descriptionstring | null

      length: ≤ 1000

    • propertiesobject[]

      items: ≤ 200

      • keystringrequired

        length: ≤ 255

      • typestringrequired

        values: "string", "number", "boolean", "datetime", "list", "object"

      • requiredboolean

        default: false

      • valuesstring | number[] | null
        Allowed values (strings or numbers; only for string and number properties)

        items: ≤ 100

        One of:

      • descriptionstring | null

        length: ≤ 1000

EventSchemaViolation

  • kindstring

    values: "unplanned_event", "unplanned_property", "missing_property", "wrong_type", "unexpected_value"

  • eventstring
  • propertystring | null
  • countinteger
  • last_atstring (date-time)
  • examplestring | null

Approval

  • requiredboolean
    The project requires approval before launch.
  • statusstring
    Approval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.

    values: "pending", "approved", "returned"

  • approved_bystring
  • approved_atstring (date-time)
  • changedboolean
    Approved, but changed since approval: launch will send it back to review.
  • historyobject[]
    • actionstring

      values: "requested", "approved", "returned", "changed"

    • commentstring
    • userstring
    • via_apiboolean
    • atstring (date-time)

AssistantsQuery

  • eventstring
    Purchase event; defaults to the purchase event of the project settings. Without it the report has no purchases
  • amountstring
    Numeric property with the order amount

AssistantsResult

  • definitionobjectrequired
    Normalized definition
  • periodobjectrequired
    • fromstring (date)
    • tostring (date)
  • currencystring | null
  • purchasesboolean
  • attribution_daysinteger
  • summaryobjectrequired
    current and previous period: requests, searches, product_clicks, carts, cart_clicks, assistant_orders, visits, visitors, orders, revenue
  • assistantsobject[]required
  • chartobjectrequired
    buckets and per assistant requests and visits by bucket
  • queriesobject[]required
    • querystring
    • countinteger
    • emptyinteger
      Searches without results
  • productsobject[]required
    • idstring
    • namestring | null
    • requestsinteger
    • clicksinteger