Меню
OneTrace.pro

Справочник API

Приём событий, профили, сегменты, цепочки и рассылки — спецификация OpenAPI 3.1.

Общие сведения

Описания методов и полей — на английском, как в спецификации.

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.

Базовый адрес: https://cdp.onetrace.pro/api/v1

Ключи

  • 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

Ключ: writeKey или secretKey

Тело запросаобязательно

Message

  • typestring

    значения: "track", "identify", "page", "screen", "alias"

  • messageIdstring

    длина: ≤ 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.

    длина: ≤ 128

  • previousIdstring | integer
  • eventstring

    длина: ≤ 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.

    элементов: ≤ 20

    • channelstringобязательно

      шаблон: ^[a-z0-9_]{1,64}$ · пример: "email"

    • topicstring
      Subscription topic; the whole channel if omitted.

      шаблон: ^[a-z0-9_-]{1,64}$

    • statusstringобязательно

      значения: "subscribed", "unsubscribed"

  • timestampstring (date-time)
Пример тела запроса
{
  "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"
}

Ответы

  • 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

Ключ: writeKey или secretKey

Тело запросаобязательно

Message

  • typestring

    значения: "track", "identify", "page", "screen", "alias"

  • messageIdstring

    длина: ≤ 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.

    длина: ≤ 128

  • previousIdstring | integer
  • eventstring

    длина: ≤ 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.

    элементов: ≤ 20

    • channelstringобязательно

      шаблон: ^[a-z0-9_]{1,64}$ · пример: "email"

    • topicstring
      Subscription topic; the whole channel if omitted.

      шаблон: ^[a-z0-9_-]{1,64}$

    • statusstringобязательно

      значения: "subscribed", "unsubscribed"

  • timestampstring (date-time)
Пример тела запроса
{
  "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"
}

Ответы

  • 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

Ключ: writeKey или secretKey

Тело запросаобязательно

Message

  • typestring

    значения: "track", "identify", "page", "screen", "alias"

  • messageIdstring

    длина: ≤ 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.

    длина: ≤ 128

  • previousIdstring | integer
  • eventstring

    длина: ≤ 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.

    элементов: ≤ 20

    • channelstringобязательно

      шаблон: ^[a-z0-9_]{1,64}$ · пример: "email"

    • topicstring
      Subscription topic; the whole channel if omitted.

      шаблон: ^[a-z0-9_-]{1,64}$

    • statusstringобязательно

      значения: "subscribed", "unsubscribed"

  • timestampstring (date-time)
Пример тела запроса
{
  "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"
}

Ответы

  • 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

Ключ: writeKey или secretKey

Тело запросаобязательно

Message

  • typestring

    значения: "track", "identify", "page", "screen", "alias"

  • messageIdstring

    длина: ≤ 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.

    длина: ≤ 128

  • previousIdstring | integer
  • eventstring

    длина: ≤ 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.

    элементов: ≤ 20

    • channelstringобязательно

      шаблон: ^[a-z0-9_]{1,64}$ · пример: "email"

    • topicstring
      Subscription topic; the whole channel if omitted.

      шаблон: ^[a-z0-9_-]{1,64}$

    • statusstringобязательно

      значения: "subscribed", "unsubscribed"

  • timestampstring (date-time)
Пример тела запроса
{
  "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"
}

Ответы

  • 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

Ключ: writeKey или secretKey

Тело запросаобязательно

Message

  • typestring

    значения: "track", "identify", "page", "screen", "alias"

  • messageIdstring

    длина: ≤ 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.

    длина: ≤ 128

  • previousIdstring | integer
  • eventstring

    длина: ≤ 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.

    элементов: ≤ 20

    • channelstringобязательно

      шаблон: ^[a-z0-9_]{1,64}$ · пример: "email"

    • topicstring
      Subscription topic; the whole channel if omitted.

      шаблон: ^[a-z0-9_-]{1,64}$

    • statusstringобязательно

      значения: "subscribed", "unsubscribed"

  • timestampstring (date-time)
Пример тела запроса
{
  "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"
}

Ответы

  • 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

Ключ: writeKey или secretKey

Тело запросаобязательно

  • batchMessage[]обязательно

    элементов: ≤ 500

Пример тела запроса
{
  "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"
    }
  ]
}

Ответы

  • 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.

Ключ: writeKey или secretKey

Ответы

  • 200OK
    • typestringобязательно

      значения: "write", "secret"

    • namestringобязательно
    • projectobjectобязательно
      • uidstring
      • namestring
      • timezonestring
    • scopesstring[]обязательно
      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.

Ключ: writeKey

Параметры

  • languageв строке запросаstring
    Visitor language (BCP 47).

    длина: ≤ 35

  • anonymousIdв строке запросаstring
    Visitor id: forms shown to segment members are filtered by the visitor's profile.

    длина: ≤ 255

Ответы

  • 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

Ключ: writeKey или secretKey

Ответы

  • 200Public key of the project's Web Push integration
    • public_keystringобязательно
      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

Ключ: writeKey или secretKey

Тело запросаобязательно

  • anonymousIdstring
    Required without userId

    длина: ≤ 255

  • userIdstring

    длина: ≤ 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.

    длина: ≤ 128

  • publicKeystring
    VAPID key the subscription was created with
  • subscriptionobjectобязательно
    PushSubscription.toJSON(); the endpoint must belong to a browser push service
    • endpointstring (uri)обязательно
    • expirationTimeinteger | null
    • keysobjectобязательно
      • p256dhstringобязательно
      • authstringобязательно
Пример тела запроса
{
  "anonymousId": "string",
  "userId": "string",
  "userHash": "string",
  "publicKey": "string",
  "subscription": {
    "endpoint": "https://example.com",
    "expirationTime": 0,
    "keys": {
      "p256dh": "string",
      "auth": "string"
    }
  }
}

Ответы

  • 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

Ключ: writeKey или secretKey

Тело запросаобязательно

  • endpointstringобязательно
Пример тела запроса
{
  "endpoint": "string"
}

Ответы

  • 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.

Ключ: writeKey или secretKey

Тело запросаобязательно

  • installationIdstringобязательно
    Random id the SDK generates once per installation

    шаблон: ^[A-Za-z0-9_-]{8,64}$

  • anonymousIdstring
    Required without userId

    длина: ≤ 255

  • userIdstring

    длина: ≤ 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.

    длина: ≤ 128

  • appobjectобязательно
    • idstringобязательно
      iOS bundle id or Android package name
    • versionstring
    • buildstring
  • osobjectобязательно
    • namestringобязательно

      значения: "ios", "android"

    • versionstring
  • deviceobject
    • manufacturerstring
    • modelstring
  • localestring

    длина: ≤ 35

  • timezonestring
    IANA time zone

    длина: ≤ 64

  • pushobject
    • providerstring

      значения: "fcm", "apns"

    • tokenstring

      длина: ≤ 4096

    • enabledboolean
      Notifications are allowed by the user
  • sdkobject
    • namestring
    • versionstring
Пример тела запроса
{
  "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"
  }
}

Ответы

  • 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).

Ключ: writeKey или secretKey

Тело запросаобязательно

  • tokenstringобязательно
    cdp_token from the notification data

    длина: ≤ 100

  • eventstringобязательно

    значения: "received", "opened"

  • urlstring
    The link opened by the tap (cdp_url)

    длина: ≤ 2000

Пример тела запроса
{
  "token": "string",
  "event": "received",
  "url": "string"
}

Ответы

  • 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.

Ключ: writeKey или secretKey

Параметры

  • anonymousIdв строке запросаstringобязательно

    длина: ≤ 255

  • appIdв строке запросаstringобязательно
    Bundle id or package name
  • platformв строке запросаstringобязательно

    значения: "ios", "android"

Ответы

  • 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

        значения: "modal", "banner", "fullscreen"

      • positionstring

        значения: "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.

Ключ: writeKey или secretKey

Тело запросаобязательно

  • tokenstringобязательно

    длина: ≤ 100

  • eventstringобязательно

    значения: "shown", "clicked", "dismissed"

  • urlstring

    длина: ≤ 2000

Пример тела запроса
{
  "token": "string",
  "event": "shown",
  "url": "string"
}

Ответы

  • 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.

Ключ: writeKey или secretKey

Параметры

  • anonymousIdв строке запросаstringобязательно

    длина: ≤ 255

Ответы

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

        значения: "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.

Ключ: writeKey или secretKey

Ответы

  • 200Settings
    • enabledboolean
    • placementstring

      значения: "button", "element", "chat"

    • positionstring

      значения: "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.

Ключ: writeKey или secretKey

Тело запросаобязательно

  • tokenstringобязательно

    длина: ≤ 100

  • eventstringобязательно

    значения: "shown", "clicked", "dismissed"

  • urlstring

    длина: ≤ 2000

Пример тела запроса
{
  "token": "string",
  "event": "shown",
  "url": "string"
}

Ответы

  • 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).

Ключ: writeKey или secretKey

Параметры

  • typeв строке запросаstringобязательно

    значения: "personal", "popular", "trending", "viewed_with", "bought_with", "similar", "recently_viewed", "replenish"

  • limitв строке запросаinteger

    по умолчанию: 8 · диапазон: 1–24

  • itemв строке запросаstring
    Context product id (or item[] for a cart) for viewed_with, bought_with, similar.
  • categoryв строке запросаstring
    Category id for popular and trending.
  • exclude[]в строке запросаstring[]
  • anonymousIdв строке запросаstring
  • image_widthв строке запросаinteger
    Card image width (image), px. Variants for are in srcset when imgproxy is configured (ADR-047).

    по умолчанию: 480 · диапазон: 64–1200

  • languageв строке запросаstring
    Visitor language (BCP 47, as in context.locale): product names and links come in the catalog translation for the closest language (ADR-080).

    длина: ≤ 35

Ответы

  • 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).

Ключ: writeKey или secretKey

Параметры

  • uidв путиstringобязательно

    шаблон: ^[a-z0-9]{1,16}$

  • item[]в строке запросаstring[]
    Context product ids (data-item): page product or cart items.
  • categoryв строке запросаstring
    Category id (data-category); overrides the widget category.
  • exclude[]в строке запросаstring[]
  • anonymousIdв строке запросаstring
  • languageв строке запросаstring
    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).

    длина: ≤ 35

  • urlв строке запросаstring
    Page address without the domain (path and query): display rules by pages (ADR-139).

    длина: ≤ 2000

  • deviceв строке запросаstring
    Visitor device for the display rules (ADR-139).

    значения: "desktop", "mobile"

  • visitorв строке запросаstring
    New (first session on the website) or returning visitor for the display rules (ADR-139).

    значения: "new", "returning"

  • previewв строке запросаstring
    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).

    длина: ≤ 200

Ответы

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

        значения: "active", "paused"

      • settingsobject
        • titlestring
        • layoutstring

          значения: "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).

Ключ: writeKey или secretKey

Параметры

  • uidв путиstringобязательно

    шаблон: ^[a-z0-9]{1,16}$

  • anonymousIdв строке запросаstring
  • languageв строке запросаstring
    Visitor language (BCP 47, as in context.locale): the banner texts and the HTML come in their translation for the closest language.

    длина: ≤ 35

  • urlв строке запросаstring
    Page address without the domain (path and query): display rules by pages.

    длина: ≤ 2000

  • deviceв строке запросаstring
    Visitor device for the display rules.

    значения: "desktop", "mobile"

  • visitorв строке запросаstring
    New (first session on the website) or returning visitor for the display rules.

    значения: "new", "returning"

  • previewв строке запросаstring
    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.

    длина: ≤ 200

Ответы

  • 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

Ключ: не нужен

Ответы

  • 200OK

    object

Profiles

Get a profile by any identifier

get/profiles/{type}/{value}

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

Ключ: secretKey · Права: profiles.read

Параметры

  • typeв путиstringобязательно

    значения: "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"

  • valueв путиstringобязательно
    Normalized like at ingestion (lower-case email, E.164 phone).

Ответы

  • 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}

Ключ: secretKey · Права: profiles.delete

Параметры

  • typeв путиstringобязательно

    значения: "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"

  • valueв путиstringобязательно
    Normalized like at ingestion (lower-case email, E.164 phone).

Ответы

  • 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

Ключ: secretKey · Права: profiles.read

Параметры

  • typeв путиstringобязательно

    значения: "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"

  • valueв путиstringобязательно
    Normalized like at ingestion (lower-case email, E.164 phone).
  • beforeв строке запросаstring (date-time)
    Cursor: next_before of the previous page.
  • nameв строке запросаstring

Ответы

  • 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

Ключ: secretKey · Права: profiles.write

Параметры

  • typeв путиstringобязательно

    значения: "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"

  • valueв путиstringобязательно
    Normalized like at ingestion (lower-case email, E.164 phone).

Тело запросаобязательно

  • channelstringобязательно
    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.

    пример: "email"

  • topicstring
    Omit for the whole channel (all).
  • statusstringобязательно

    значения: "subscribed", "unsubscribed"

Пример тела запроса
{
  "channel": "email",
  "topic": "string",
  "status": "subscribed"
}

Ответы

  • 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.

Ключ: secretKey · Права: profiles.read

Параметры

  • typeв путиstringобязательно

    значения: "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"

  • valueв путиstringобязательно
    Normalized like at ingestion (lower-case email, E.164 phone).
  • languageв строке запросаstring
    Language of topic names; the project default when omitted.

Ответы

  • 200OK

    ProfilePreferences

    • profile_idinteger
    • languagestring
      Language of topic names.

      пример: "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

        пример: "email"

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

        пример: "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

        пример: "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.

      значения: "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

Ключ: secretKey · Права: profiles.write

Параметры

  • typeв путиstringобязательно

    значения: "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"

  • valueв путиstringобязательно
    Normalized like at ingestion (lower-case email, E.164 phone).

Тело запросаобязательно

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

    пример: {"news":{"email":true},"offers":{"email":false}}

  • frequencystring | null
    Omit to keep.

    значения: "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).
Пример тела запроса
{
  "topics": {
    "news": {
      "email": true
    },
    "offers": {
      "email": false
    }
  },
  "frequency": "weekly",
  "paused_until": "2026-01-01T10:00:00Z",
  "unsubscribe_all": true,
  "language": "string",
  "ads": true
}

Ответы

  • 200OK

    ProfilePreferences

    • profile_idinteger
    • languagestring
      Language of topic names.

      пример: "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

        пример: "email"

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

        пример: "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

        пример: "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.

      значения: "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).

Ключ: secretKey · Права: profiles.read

Параметры

  • typeв путиstringобязательно

    значения: "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"

  • valueв путиstringобязательно
    Normalized like at ingestion (lower-case email, E.164 phone).
  • languageв строке запросаstring
    Language of topic names; the project default when omitted.

Ответы

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

        значения: "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.

Ключ: secretKey · Права: profiles.read

Ответы

  • 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

Ключ: secretKey · Права: products.write

Тело запросаобязательно

  • itemsProductInput[]обязательно

    элементов: ≤ 1000

  • categoriesobject[]

    элементов: ≤ 1000

    • idstringобязательно
    • namestringобязательно
    • parent_idstring | null
    • translationsobject
      Category name by language (BCP 47 tag → {name}).

      ключей: ≤ 20

Пример тела запроса
{
  "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": {}
    }
  ]
}

Ответы

  • 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

Ключ: secretKey · Права: products.write

Тело запросаобязательно

  • idsstring[]обязательно

    элементов: 1–1000

Пример тела запроса
{
  "ids": [
    "string"
  ]
}

Ответы

  • 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.

Ключ: writeKey или secretKey

Параметры

  • productв строке запросаstringобязательно
    Product id from the catalog.

    длина: ≤ 128

  • pageв строке запросаinteger

    по умолчанию: 1 · диапазон: 1–1000

  • languageв строке запросаstring
    Language of the product name.

    длина: ≤ 35

Ответы

  • 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

        диапазон: 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

Ключ: secretKey · Права: products.write

Тело запросаобязательно

  • productstringобязательно
    Product id from the catalog.

    длина: ≤ 128

  • identityIdentityRefобязательно
  • ratingintegerобязательно

    диапазон: 1–5

  • titlestring

    длина: ≤ 120

  • textstring

    длина: ≤ 2000

  • authorstring
    Name shown with the review.

    длина: ≤ 60

  • languagestring

    длина: ≤ 35

  • publishboolean

    по умолчанию: false

  • datestring (date-time)
    Date of a moved review (with publish).
Пример тела запроса
{
  "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"
}

Ответы

  • 201Saved
    • idinteger
    • statusstring

      значения: "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.

Ключ: writeKey или secretKey

Тело запросаобязательно

  • product_idstringобязательно
    Product id in the catalog (id from the feed or the products API)

    длина: ≤ 128

  • questionstringобязательно

    длина: ≤ 500

  • anonymousIdstringобязательно

    длина: ≤ 255

  • userIdstring

    длина: ≤ 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.

    длина: ≤ 128

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

    длина: ≤ 35

  • asyncboolean
    Answer in the background: 202 with id instead of waiting for the model (the tracker widget does so)
Пример тела запроса
{
  "product_id": "string",
  "question": "string",
  "anonymousId": "string",
  "userId": "string",
  "userHash": "string",
  "language": "string",
  "async": true
}

Ответы

  • 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.

Ключ: writeKey или secretKey

Параметры

  • idв строке запросаstringобязательно

    длина: 40–40

Ответы

  • 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.

Ключ: writeKey или secretKey

Параметры

  • product_idв строке запросаstringобязательно

    длина: ≤ 128

  • languageв строке запросаstring

    длина: ≤ 35

Ответы

  • 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.

Ключ: writeKey или secretKey

Параметры

  • languageв строке запросаstring

    длина: ≤ 35

Ответы

  • 200Widget settings
    • enabledbooleanобязательно
    • modestring

      значения: "block", "chat"

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

      пример: "#4f46e5"

    • radiusinteger

      диапазон: 0–24

    • textsobject

Stores

List stores

get/stores

Ключ: secretKey · Права: products.read

Ответы

  • 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

Ключ: secretKey · Права: products.write

Тело запросаобязательно

  • itemsStore[]обязательно

    элементов: 1–1000

Пример тела запроса
{
  "items": [
    {
      "id": "string",
      "name": "string",
      "city": "string",
      "address": "string"
    }
  ]
}

Ответы

  • 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

Ключ: secretKey · Права: products.write

Тело запросаобязательно

  • idsstring[]обязательно

    элементов: 1–1000

Пример тела запроса
{
  "ids": [
    "string"
  ]
}

Ответы

  • 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

Ключ: secretKey · Права: events.read

Ответы

  • 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

Ключ: secretKey · Права: events.read

Ответы

  • 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.

Ключ: secretKey · Права: events.read

Ответы

  • 200OK

    EventSchema

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

      элементов: ≤ 1000

      • namestringобязательно
        Event name (system $… events are not allowed)

        длина: ≤ 255

      • labelstring | null

        длина: ≤ 255

      • descriptionstring | null

        длина: ≤ 1000

      • propertiesobject[]

        элементов: ≤ 200

        • keystringобязательно

          длина: ≤ 255

        • typestringобязательно

          значения: "string", "number", "boolean", "datetime", "list", "object"

        • requiredboolean

          по умолчанию: false

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

          элементов: ≤ 100

          Один из вариантов:

        • descriptionstring | null

          длина: ≤ 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).

Ключ: secretKey · Права: events.manage_schema

Тело запросаобязательно

EventSchema

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

    элементов: ≤ 1000

    • namestringобязательно
      Event name (system $… events are not allowed)

      длина: ≤ 255

    • labelstring | null

      длина: ≤ 255

    • descriptionstring | null

      длина: ≤ 1000

    • propertiesobject[]

      элементов: ≤ 200

      • keystringобязательно

        длина: ≤ 255

      • typestringобязательно

        значения: "string", "number", "boolean", "datetime", "list", "object"

      • requiredboolean

        по умолчанию: false

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

        элементов: ≤ 100

        Один из вариантов:

      • descriptionstring | null

        длина: ≤ 1000

Пример тела запроса
{
  "enabled": true,
  "events": [
    {
      "name": "string",
      "label": "string",
      "description": "string",
      "properties": [
        {
          "key": "string",
          "type": "string",
          "required": false,
          "values": [
            "string"
          ],
          "description": "string"
        }
      ]
    }
  ]
}

Ответы

  • 200Saved

    EventSchema

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

      элементов: ≤ 1000

      • namestringобязательно
        Event name (system $… events are not allowed)

        длина: ≤ 255

      • labelstring | null

        длина: ≤ 255

      • descriptionstring | null

        длина: ≤ 1000

      • propertiesobject[]

        элементов: ≤ 200

        • keystringобязательно

          длина: ≤ 255

        • typestringобязательно

          значения: "string", "number", "boolean", "datetime", "list", "object"

        • requiredboolean

          по умолчанию: false

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

          элементов: ≤ 100

          Один из вариантов:

        • descriptionstring | null

          длина: ≤ 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.

Ключ: secretKey · Права: events.read

Ответы

  • 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

Ключ: secretKey · Права: segments.read

Параметры

  • limitв строке запросаinteger

    по умолчанию: 50 · диапазон: 1–200

  • cursorв строке запросаstring

Ответы

  • 200OK
    • dataSegment[]обязательно
    • next_cursorstring | nullобязательно
      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).

Ключ: secretKey · Права: segments.write

Параметры

  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

SegmentInput

  • namestringобязательно

    длина: ≤ 120

  • descriptionstring | null
  • typestringобязательно

    значения: "dynamic", "static"

  • realtimeboolean
  • schedule_minutesinteger

    значения: 15, 30, 60, 180, 360, 720, 1440

  • rulesobject
Пример тела запроса
{
  "name": "string",
  "description": "string",
  "type": "dynamic",
  "realtime": true,
  "schedule_minutes": 15,
  "rules": {}
}

Ответы

  • 201Created

    SegmentDetail

    Все поля 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}

Ключ: secretKey · Права: segments.read

Параметры

  • segmentв путиintegerобязательно

Ответы

  • 200OK

    SegmentDetail

    Все поля 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.

Ключ: secretKey · Права: segments.write

Параметры

  • segmentв путиintegerобязательно

Тело запросаобязательно

SegmentPatch

  • namestring

    длина: ≤ 120

  • descriptionstring | null
  • realtimeboolean
  • schedule_minutesinteger
  • rulesobject
Пример тела запроса
{
  "name": "string",
  "description": "string",
  "realtime": true,
  "schedule_minutes": 0,
  "rules": {}
}

Ответы

  • 200OK

    SegmentDetail

    Все поля 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.

Ключ: secretKey · Права: segments.write

Параметры

  • segmentв путиintegerобязательно

Ответы

  • 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

Ключ: secretKey · Права: segments.write

Параметры

  • segmentв путиintegerобязательно

Ответы

  • 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

Ключ: secretKey · Права: segments.read

Параметры

  • segmentв путиintegerобязательно
  • limitв строке запросаinteger

    по умолчанию: 50 · диапазон: 1–200

  • cursorв строке запросаstring

Ответы

  • 200OK
    • dataobject[]обязательно
      • profile_idinteger
      • entered_atstring (date-time)
    • next_cursorstring | nullобязательно
      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

Ключ: secretKey · Права: segments.write

Параметры

  • segmentв путиintegerобязательно
  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

IdentitiesInput

  • identitiesIdentityRef[]обязательно

    элементов: 1–1000

Пример тела запроса
{
  "identities": [
    {
      "type": "user_id",
      "value": "string"
    }
  ]
}

Ответы

  • 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

Ключ: secretKey · Права: segments.write

Параметры

  • segmentв путиintegerобязательно

Тело запросаобязательно

IdentitiesInput

  • identitiesIdentityRef[]обязательно

    элементов: 1–1000

Пример тела запроса
{
  "identities": [
    {
      "type": "user_id",
      "value": "string"
    }
  ]
}

Ответы

  • 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}

Ключ: secretKey · Права: segments.read

Параметры

  • segmentв путиintegerобязательно
  • typeв путиstringобязательно

    значения: "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"

  • valueв путиstringобязательно
    Normalized like at ingestion (lower-case email, E.164 phone).

Ответы

  • 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

Ключ: secretKey · Права: journeys.read

Параметры

  • limitв строке запросаinteger

    по умолчанию: 50 · диапазон: 1–200

  • cursorв строке запросаstring
  • statusв строке запросаstring

    значения: "draft", "active", "paused", "archived"

Ответы

  • 200OK
    • dataJourney[]обязательно
    • next_cursorstring | nullобязательно
      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).

Ключ: secretKey · Права: journeys.write

Параметры

  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

JourneyInput

  • namestringобязательно

    длина: ≤ 120

  • descriptionstring | null
  • graphobject
    • nodesarray

      элементов: ≤ 200

    • edgesarray

      элементов: ≤ 400

  • entryobject
Пример тела запроса
{
  "name": "string",
  "description": "string",
  "graph": {
    "nodes": [],
    "edges": []
  },
  "entry": {}
}

Ответы

  • 201Created

    JourneyDetail

    Все поля 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}

Ключ: secretKey · Права: journeys.read

Параметры

  • journeyв путиintegerобязательно

Ответы

  • 200OK

    JourneyDetail

    Все поля 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}

Ключ: secretKey · Права: journeys.write

Параметры

  • journeyв путиintegerобязательно

Тело запросаобязательно

JourneyPatch

  • namestring

    длина: ≤ 120

  • descriptionstring | null
  • graphobject
  • entryobject
Пример тела запроса
{
  "name": "string",
  "description": "string",
  "graph": {},
  "entry": {}
}

Ответы

  • 200OK

    JourneyDetail

    Все поля 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.

Ключ: secretKey · Права: journeys.read

Параметры

  • journeyв путиintegerобязательно

Ответы

  • 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).

Ключ: secretKey · Права: journeys.read

Параметры

  • journeyв путиintegerобязательно

Ответы

  • 200OK

    LaunchReadiness

    • readybooleanобязательно
      No errors: the launch will pass.
    • clearbooleanобязательно
      No errors and no warnings.
    • checksobject[]обязательно
      • keystringобязательно
        config, archived, quota, sending_domain, integration, untranslated, template_error, unsubscribe, deliverability, segment_pending, segment_empty, segment_broad, goal_missing, goal_unseen, goal_window
      • levelstringобязательно

        значения: "error", "warning", "info"

      • messagestringобязательно
        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.

Ключ: secretKey · Права: journeys.publish

Параметры

  • journeyв путиintegerобязательно
  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Ответы

  • 200OK

    JourneyDetail

    Все поля 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.

Ключ: secretKey · Права: journeys.publish

Параметры

  • journeyв путиintegerобязательно
  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запроса

  • exit_allboolean
Пример тела запроса
{
  "exit_all": true
}

Ответы

  • 200OK

    Journey

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      значения: "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.

      значения: "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.

Ключ: secretKey · Права: journeys.publish

Параметры

  • journeyв путиintegerобязательно
  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Ответы

  • 200OK

    Journey

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      значения: "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.

      значения: "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.

Ключ: secretKey · Права: journeys.publish

Параметры

  • journeyв путиintegerобязательно
  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Ответы

  • 200OK

    Journey

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      значения: "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.

      значения: "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.

Ключ: secretKey · Права: journeys.write

Параметры

  • journeyв путиintegerобязательно

Тело запроса

  • commentstring

    длина: ≤ 1000

Пример тела запроса
{
  "comment": "string"
}

Ответы

  • 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.

Ключ: secretKey · Права: journeys.approve

Параметры

  • journeyв путиintegerобязательно

Тело запроса

  • commentstring

    длина: ≤ 1000

Пример тела запроса
{
  "comment": "string"
}

Ответы

  • 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.

Ключ: secretKey · Права: journeys.approve

Параметры

  • journeyв путиintegerобязательно

Тело запросаобязательно

  • commentstringобязательно

    длина: ≤ 1000

Пример тела запроса
{
  "comment": "string"
}

Ответы

  • 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

Ключ: secretKey · Права: journeys.read

Параметры

  • journeyв путиintegerобязательно
  • limitв строке запросаinteger

    по умолчанию: 50 · диапазон: 1–200

  • cursorв строке запросаstring
  • statusв строке запросаstring

    значения: "active", "waiting", "completed", "exited", "failed"

Ответы

  • 200OK
    • dataEnrollment[]обязательно
    • next_cursorstring | nullобязательно
      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

Ключ: secretKey · Права: journeys.read, analytics.read

Параметры

  • journeyв путиintegerобязательно
  • periodв строке запросаinteger

    значения: 7, 30, 90 · по умолчанию: 30

Ответы

  • 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

Ключ: secretKey · Права: journeys.write

Параметры

  • journeyв путиintegerобязательно
  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

  • identityIdentityRefобязательно
  • dataobject
    Available in templates as context.data.
  • idempotency_keystring

    длина: ≤ 150

Пример тела запроса
{
  "identity": {
    "type": "user_id",
    "value": "string"
  },
  "data": {},
  "idempotency_key": "string"
}

Ответы

  • 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

Ключ: secretKey · Права: templates.read

Параметры

  • limitв строке запросаinteger

    по умолчанию: 50 · диапазон: 1–200

  • cursorв строке запросаstring
  • channelв строке запросаstring
    Only templates of this channel.

Ответы

  • 200OK
    • dataMessageTemplate[]обязательно
    • next_cursorstring | nullобязательно
      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.

Ключ: secretKey · Права: templates.write

Параметры

  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

MessageTemplateInput

  • namestringобязательно

    длина: ≤ 120

  • channel_keystringобязательно
    Channel of the template; cannot be changed later.
  • topicstring

    по умолчанию: "marketing" · длина: ≤ 64 · шаблон: ^[a-z0-9_-]+$

  • transactionalboolean

    по умолчанию: false

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

    длина: ≤ 16 · пример: "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.

    ключей: ≤ 50

Пример тела запроса
{
  "name": "string",
  "channel_key": "string",
  "topic": "marketing",
  "transactional": false,
  "language": "de",
  "content": {},
  "translations": {}
}

Ответы

  • 201Created

    MessageTemplate

    • idinteger
    • namestring
    • channelstring

      пример: "email"

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

      длина: ≤ 16 · пример: "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}

Ключ: secretKey · Права: templates.read

Параметры

  • templateв путиintegerобязательно

Ответы

  • 200OK

    MessageTemplate

    • idinteger
    • namestring
    • channelstring

      пример: "email"

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

      длина: ≤ 16 · пример: "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.

Ключ: secretKey · Права: templates.write

Параметры

  • templateв путиintegerобязательно

Тело запросаобязательно

  • namestring

    длина: ≤ 120

  • topicstring

    по умолчанию: "marketing" · длина: ≤ 64 · шаблон: ^[a-z0-9_-]+$

  • transactionalboolean

    по умолчанию: false

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

    длина: ≤ 16 · пример: "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.

    ключей: ≤ 50

Пример тела запроса
{
  "name": "string",
  "topic": "marketing",
  "transactional": false,
  "language": "de",
  "content": {},
  "translations": {}
}

Ответы

  • 200OK

    MessageTemplate

    • idinteger
    • namestring
    • channelstring

      пример: "email"

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

      длина: ≤ 16 · пример: "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.

Ключ: secretKey · Права: templates.write

Параметры

  • templateв путиintegerобязательно

Ответы

  • 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

Ключ: secretKey · Права: campaigns.read

Параметры

  • limitв строке запросаinteger

    по умолчанию: 50 · диапазон: 1–200

  • cursorв строке запросаstring

Ответы

  • 200OK
    • dataCampaign[]обязательно
    • next_cursorstring | nullобязательно
      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.

Ключ: secretKey · Права: campaigns.write

Параметры

  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

CampaignInput

  • namestringобязательно

    длина: ≤ 120

  • descriptionstring | null
  • integration_idinteger | null
    Channel integration; the template of every variant must belong to its channel.
  • audienceCampaignAudienceобязательно
  • variantsCampaignVariant[]обязательно

    элементов: 1–5

  • scheduleCampaignScheduleобязательно
  • rate_per_minuteinteger | null

    диапазон: 10–100000

Пример тела запроса
{
  "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"
    }
  }
}

Ответы

  • 201Created

    Campaign

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      значения: "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.

      значения: "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}

Ключ: secretKey · Права: campaigns.read

Параметры

  • campaignв путиintegerобязательно

Ответы

  • 200OK

    Campaign

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      значения: "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.

      значения: "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.

Ключ: secretKey · Права: campaigns.write

Параметры

  • campaignв путиintegerобязательно

Тело запросаобязательно

Пример тела запроса
{
  "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"
    }
  }
}

Ответы

  • 200OK

    Campaign

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      значения: "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.

      значения: "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.

Ключ: secretKey · Права: campaigns.write

Параметры

  • campaignв путиintegerобязательно

Ответы

  • 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

Ключ: secretKey · Права: campaigns.read

Параметры

  • campaignв путиintegerобязательно

Ответы

  • 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).

Ключ: secretKey · Права: campaigns.read

Параметры

  • campaignв путиintegerобязательно

Ответы

  • 200OK

    LaunchReadiness

    • readybooleanобязательно
      No errors: the launch will pass.
    • clearbooleanобязательно
      No errors and no warnings.
    • checksobject[]обязательно
      • keystringобязательно
        config, archived, quota, sending_domain, integration, untranslated, template_error, unsubscribe, deliverability, segment_pending, segment_empty, segment_broad, goal_missing, goal_unseen, goal_window
      • levelstringобязательно

        значения: "error", "warning", "info"

      • messagestringобязательно
        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.

Ключ: secretKey · Права: campaigns.send

Параметры

  • campaignв путиintegerобязательно
  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Ответы

  • 200OK

    Campaign

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      значения: "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.

      значения: "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.

Ключ: secretKey · Права: campaigns.send

Параметры

  • campaignв путиintegerобязательно
  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Ответы

  • 200OK

    Campaign

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      значения: "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.

      значения: "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.

Ключ: secretKey · Права: campaigns.send

Параметры

  • campaignв путиintegerобязательно
  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Ответы

  • 200OK

    Campaign

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      значения: "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.

      значения: "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.

Ключ: secretKey · Права: campaigns.send

Параметры

  • campaignв путиintegerобязательно
  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Ответы

  • 200OK

    Campaign

    • idinteger
    • namestring
    • descriptionstring | null
    • statusstring

      значения: "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.

      значения: "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.

Ключ: secretKey · Права: campaigns.write

Параметры

  • campaignв путиintegerобязательно

Тело запроса

  • commentstring

    длина: ≤ 1000

Пример тела запроса
{
  "comment": "string"
}

Ответы

  • 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.

Ключ: secretKey · Права: campaigns.approve

Параметры

  • campaignв путиintegerобязательно

Тело запроса

  • commentstring

    длина: ≤ 1000

Пример тела запроса
{
  "comment": "string"
}

Ответы

  • 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.

Ключ: secretKey · Права: campaigns.approve

Параметры

  • campaignв путиintegerобязательно

Тело запросаобязательно

  • commentstringобязательно

    длина: ≤ 1000

Пример тела запроса
{
  "comment": "string"
}

Ответы

  • 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.

Ключ: writeKey или secretKey

Параметры

  • languageв строке запросаstring

    длина: ≤ 35

Ответы

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

      значения: "right", "left"

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

      значения: "hidden", "optional", "required"

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

      значения: "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

        значения: "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.

Ключ: writeKey или secretKey

Параметры

  • conversationв строке запросаstring (uuid)обязательно
  • tokenв строке запросаstringобязательно

    длина: ≤ 64

  • afterв строке запросаinteger

    диапазон: ≥ 0

  • readв строке запросаboolean
    Mark operator replies as read by the visitor

    по умолчанию: true

Ответы

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.

Ключ: writeKey или secretKey

Тело запросаобязательно

  • anonymousIdstringобязательно

    длина: ≤ 255

  • userIdstring

    длина: ≤ 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.

    длина: ≤ 128

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

    длина: ≤ 64

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

    длина: ≤ 4000

  • namestring

    длина: ≤ 100

  • emailstring (email)

    длина: ≤ 255

  • pagestring
    Page URL (http/https)

    длина: ≤ 2000

  • languagestring

    длина: ≤ 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.

    длина: ≤ 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
Пример тела запроса
{
  "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": {}
}

Ответы

  • 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).

Ключ: writeKey или secretKey

Тело запросаобязательно

  • conversationstring (uuid)обязательно
    Conversation id from POST /chat/messages
  • tokenstringобязательно
    Visitor token of the conversation from POST /chat/messages

    длина: ≤ 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.

    длина: ≤ 4000

Пример тела запроса
{
  "conversation": "00000000-0000-0000-0000-000000000000",
  "token": "string",
  "text": "string"
}

Ответы

  • 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.

Ключ: writeKey или secretKey

Тело запросаобязательно

  • anonymousIdstringобязательно

    длина: ≤ 255

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

    длина: ≤ 2000

  • titlestring

    длина: ≤ 300

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

    длина: ≤ 2000

  • sourcestring
    utm_source of the first page or the referring host

    длина: ≤ 100

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

    диапазон: ≥ 1

  • languagestring

    длина: ≤ 35

  • conversationstring (uuid)
    Conversation the widget already knows
  • invitationsboolean
    Return the automatic invitations for this visitor
Пример тела запроса
{
  "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
}

Ответы

  • 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

      Все поля 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.

Ключ: writeKey или secretKey

Тело запросаобязательно

  • conversationstring (uuid)обязательно
  • tokenstringобязательно

    длина: ≤ 64

  • answersobjectобязательно
    Question id → answer (scale number, option or list of options, text)
  • languagestring

    длина: ≤ 35

Пример тела запроса
{
  "conversation": "00000000-0000-0000-0000-000000000000",
  "token": "string",
  "answers": {},
  "language": "string"
}

Ответы

  • 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.

Ключ: writeKey или secretKey

Тело запросаобязательно

  • conversationstring (uuid)обязательно
    Conversation id from POST /chat/messages
  • tokenstringобязательно
    Visitor token of the conversation from POST /chat/messages

    длина: ≤ 64

  • ratingintegerобязательно

    диапазон: 1–5

  • commentstring

    длина: ≤ 1000

Пример тела запроса
{
  "conversation": "00000000-0000-0000-0000-000000000000",
  "token": "string",
  "rating": 1,
  "comment": "string"
}

Ответы

  • 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.

Ключ: writeKey или secretKey

Тело запросаобязательно

  • conversationstring (uuid)обязательно
    Conversation id from POST /chat/messages
  • tokenstringобязательно
    Visitor token of the conversation from POST /chat/messages

    длина: ≤ 64

Пример тела запроса
{
  "conversation": "00000000-0000-0000-0000-000000000000",
  "token": "string"
}

Ответы

  • 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.

Ключ: writeKey или secretKey

Тело запросаобязательно

  • conversationstring (uuid)обязательно
    Conversation id from POST /chat/messages
  • tokenstringобязательно
    Visitor token of the conversation from POST /chat/messages

    длина: ≤ 64

Пример тела запроса
{
  "conversation": "00000000-0000-0000-0000-000000000000",
  "token": "string"
}

Ответы

  • 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.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

ReportQuery

Пример тела запроса
{
  "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
}

Ответы

  • 200OK

    ReportResult

    • definitionobjectобязательно
      Normalized definition
    • periodobjectобязательно
      • fromstring (date)
      • tostring (date)
    • bucketsstring (date)[]обязательно
    • seriesobject[]обязательно
      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.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

FunnelQuery

  • stepsobject[]обязательно

    элементов: 2–10

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

      диапазон: ≥ 1

    • unitstring

      значения: "minute", "hour", "day"

  • orderstring

    значения: "sequential", "strict"

  • profilesProfileRules
  • breakdownBreakdown
Пример тела запроса
{
  "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
  }
}

Ответы

  • 200OK

    FunnelResult

    • definitionobjectобязательно
      Normalized definition
    • periodobjectобязательно
      • fromstring (date)
      • tostring (date)
    • stepsobject[]обязательно
      Per step: event, reached, from_start, from_previous, median_seconds, avg_seconds
    • breakdownobject[]обязательно
      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.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

RetentionQuery

Пример тела запроса
{
  "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
  }
}

Ответы

  • 200OK

    RetentionResult

    • definitionobjectобязательно
      Normalized definition
    • periodobjectобязательно
      • fromstring (date)
      • tostring (date)
    • cohortsobject[]обязательно
      Per cohort: date, size, values (returned per period, null — not yet), open (period still running)
    • averageobject[]обязательно
      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.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

PathQuery

  • eventstringобязательно
  • directionstring

    значения: "after", "before"

  • stepsinteger

    диапазон: 1–5

  • gap_minutesinteger

    диапазон: 1–1440

  • excludestring[]

    элементов: ≤ 20

  • profilesProfileRules
Пример тела запроса
{
  "event": "string",
  "filters": [
    {
      "key": "string",
      "operator": "string",
      "value": null
    }
  ],
  "direction": "after",
  "steps": 1,
  "gap_minutes": 1,
  "exclude": [
    "string"
  ],
  "profiles": {},
  "period": {
    "last": 7
  }
}

Ответы

  • 200OK

    PathResult

    • definitionobjectобязательно
      Normalized definition
    • periodobjectобязательно
      • fromstring (date)
      • tostring (date)
    • totalintegerобязательно
    • nodesobject[]обязательно
    • linksobject[]обязательно
    • pathsobject[]обязательно
      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.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

RevenueQuery

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

    значения: "week", "month"

  • ltv_periodsinteger

    диапазон: 1–12

  • profilesProfileRules
Пример тела запроса
{
  "event": "string",
  "amount": "string",
  "product_property": "string",
  "interval": "day",
  "ltv_interval": "week",
  "ltv_periods": 1,
  "profiles": {},
  "period": {
    "last": 7
  }
}

Ответы

  • 200OK

    RevenueResult

    • definitionobjectобязательно
      Normalized definition
    • periodobjectобязательно
      • fromstring (date)
      • tostring (date)
    • currencystring | null
    • other_currency_ordersinteger
    • summaryobjectобязательно
    • seriesobjectобязательно
    • ltvobjectобязательно
    • productsobject[]обязательно
    • categoriesobject[]обязательно
  • 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.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

TrafficQuery

Пример тела запроса
{
  "dimension": "channel",
  "interval": "day",
  "event": "string",
  "amount": "string",
  "profiles": {},
  "period": {
    "last": 7
  }
}

Ответы

  • 200OK

    TrafficResult

    • definitionobjectобязательно
      Normalized definition
    • periodobjectобязательно
      • fromstring (date)
      • tostring (date)
    • currencystring | null
    • purchasesboolean
    • summaryobjectобязательно
    • rowsobject[]обязательно
    • row_countinteger
    • 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 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.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

AttributionQuery

Пример тела запроса
{
  "window_days": 1,
  "model": "last",
  "interval": "day",
  "event": "string",
  "amount": "string",
  "profiles": {},
  "period": {
    "last": 7
  }
}

Ответы

  • 200OK

    AttributionResult

    • definitionobjectобязательно
      Normalized definition
    • periodobjectобязательно
      • fromstring (date)
      • tostring (date)
    • currencystring | null
    • summaryobjectобязательно
    • channelsobject[]обязательно
      Per channel: channel, clicks, touched_orders, revenue and orders by model
    • itemsobject[]обязательно
      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.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

RopoQuery

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

    значения: 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
Пример тела запроса
{
  "window_days": 1,
  "touches": [
    "visit"
  ],
  "interval": "day",
  "event": "string",
  "amount": "string",
  "product_property": "string",
  "profiles": {},
  "period": {
    "last": 7
  }
}

Ответы

  • 200OK

    RopoResult

    • definitionobjectобязательно
      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

    • definitionobjectобязательно
      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.

Ключ: secretKey · Права: analytics.read

Тело запросаобязательно

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
Пример тела запроса
{
  "interval": "day",
  "event": "string",
  "amount": "string",
  "period": {
    "last": 7
  }
}

Ответы

  • 200OK

    AssistantsResult

    • definitionobjectобязательно
      Normalized definition
    • periodobjectобязательно
      • fromstring (date)
      • tostring (date)
    • currencystring | null
    • purchasesboolean
    • attribution_daysinteger
    • summaryobjectобязательно
      current and previous period: requests, searches, product_clicks, carts, cart_clicks, assistant_orders, visits, visitors, orders, revenue
    • assistantsobject[]обязательно
    • chartobjectобязательно
      buckets and per assistant requests and visits by bucket
    • queriesobject[]обязательно
      • querystring
      • countinteger
      • emptyinteger
        Searches without results
    • productsobject[]обязательно
      • 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

Ключ: secretKey · Права: analytics.read

Параметры

  • limitв строке запросаinteger

    по умолчанию: 50 · диапазон: 1–200

  • cursorв строке запросаstring
  • typeв строке запросаAnalyticsReportType

Ответы

  • 200OK
    • dataSavedReport[]обязательно
    • next_cursorstring | nullобязательно
      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.

Ключ: secretKey · Права: analytics.write

Параметры

  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

SavedReportInput

  • namestringобязательно

    длина: ≤ 120

  • typeAnalyticsReportTypeобязательно
  • definitionobjectобязательно
    Definition of the report type — see the run operations
  • viewobject
Пример тела запроса
{
  "name": "string",
  "type": "report",
  "definition": {},
  "view": {}
}

Ответы

  • 201Created

    SavedReportDetail

    Все поля SavedReport:

    • definitionobjectобязательно
    • viewobjectобязательно
      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}

Ключ: secretKey · Права: analytics.read

Параметры

  • reportв путиintegerобязательно

Ответы

  • 200OK

    SavedReportDetail

    Все поля SavedReport:

    • definitionobjectобязательно
    • viewobjectобязательно
      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.

Ключ: secretKey · Права: analytics.write

Параметры

  • reportв путиintegerобязательно

Тело запросаобязательно

SavedReportPatch

  • namestring

    длина: ≤ 120

  • definitionobject
  • viewobject
Пример тела запроса
{
  "name": "string",
  "definition": {},
  "view": {}
}

Ответы

  • 200OK

    SavedReportDetail

    Все поля SavedReport:

    • definitionobjectобязательно
    • viewobjectобязательно
      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.

Ключ: secretKey · Права: analytics.write

Параметры

  • reportв путиintegerобязательно

Ответы

  • 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.

Ключ: secretKey · Права: analytics.read

Параметры

  • reportв путиintegerобязательно

Тело запросаобязательно

Пример тела запроса
{
  "period": {
    "last": 7
  }
}

Ответы

  • 200OK

    Объект с произвольными ключами.

  • 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

Ключ: secretKey · Права: analytics.read

Параметры

  • limitв строке запросаinteger

    по умолчанию: 50 · диапазон: 1–200

  • cursorв строке запросаstring

Ответы

  • 200OK
    • dataDashboard[]обязательно
    • next_cursorstring | nullобязательно
      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

Ключ: secretKey · Права: analytics.write

Параметры

  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

DashboardInput

  • namestringобязательно

    длина: ≤ 120

  • layoutobject[]

    элементов: ≤ 24

    • report_idintegerобязательно
    • sizestring

      значения: "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.
Пример тела запроса
{
  "name": "string",
  "layout": [
    {
      "report_id": 0,
      "size": "half"
    }
  ],
  "period": {
    "last": 7
  },
  "main": true
}

Ответы

  • 201Created

    Dashboard

    • idintegerобязательно
    • namestringобязательно
    • layoutobject[]обязательно

      элементов: ≤ 24

      • report_idintegerобязательно
      • sizestring

        значения: "half", "full"

    • periodAnalyticsPeriodобязательно
    • mainbooleanобязательно
      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)обязательно
    • 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 dashboard

get/analytics/dashboards/{dashboard}

Ключ: secretKey · Права: analytics.read

Параметры

  • dashboardв путиintegerобязательно

Ответы

  • 200OK

    Dashboard

    • idintegerобязательно
    • namestringобязательно
    • layoutobject[]обязательно

      элементов: ≤ 24

      • report_idintegerобязательно
      • sizestring

        значения: "half", "full"

    • periodAnalyticsPeriodобязательно
    • mainbooleanобязательно
      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)обязательно
    • 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 dashboard

patch/analytics/dashboards/{dashboard}

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

Ключ: secretKey · Права: analytics.write

Параметры

  • dashboardв путиintegerобязательно

Тело запросаобязательно

DashboardPatch

  • namestring

    длина: ≤ 120

  • layoutobject[]

    элементов: ≤ 24

    • report_idintegerобязательно
    • sizestring

      значения: "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.
Пример тела запроса
{
  "name": "string",
  "layout": [
    {
      "report_id": 0,
      "size": "half"
    }
  ],
  "period": {
    "last": 7
  },
  "main": true
}

Ответы

  • 200OK

    Dashboard

    • idintegerобязательно
    • namestringобязательно
    • layoutobject[]обязательно

      элементов: ≤ 24

      • report_idintegerобязательно
      • sizestring

        значения: "half", "full"

    • periodAnalyticsPeriodобязательно
    • mainbooleanобязательно
      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)обязательно
    • 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 dashboard

delete/analytics/dashboards/{dashboard}

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

Ключ: secretKey · Права: analytics.write

Параметры

  • dashboardв путиintegerобязательно

Ответы

  • 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.

Ключ: secretKey · Права: analytics.read

Параметры

  • limitв строке запросаinteger

    по умолчанию: 50 · диапазон: 1–200

  • cursorв строке запросаstring

Ответы

  • 200OK
    • dataControlGroupPeriod[]обязательно
    • next_cursorstring | nullобязательно
      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.

Ключ: secretKey · Права: analytics.read

Параметры

  • periodв путиintegerобязательно

Ответы

  • 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

        элементов: 2–2

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

        элементов: 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

        значения: "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).

Ключ: secretKey · Права: loyalty.read

Тело запросаобязательно

  • profileLoyaltyProfileRefобязательно
  • amountnumberобязательно
    Cart amount in the project currency

    диапазон: ≥ 0

Пример тела запроса
{
  "profile": {
    "type": "user_id",
    "value": "string"
  },
  "amount": 0
}

Ответы

  • 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.

Ключ: secretKey · Права: loyalty.read

Параметры

  • typeв путиstringобязательно

    значения: "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"

  • valueв путиstringобязательно
    Normalized like at ingestion (lower-case email, E.164 phone).

Ответы

  • 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.

Ключ: secretKey · Права: loyalty.read

Параметры

  • typeв путиstringобязательно

    значения: "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"

  • valueв путиstringобязательно
    Normalized like at ingestion (lower-case email, E.164 phone).
  • limitв строке запросаinteger

    по умолчанию: 50 · диапазон: 1–200

  • cursorв строке запросаstring

Ответы

  • 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.

Ключ: secretKey · Права: loyalty.write

Параметры

  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

Пример тела запроса
{
  "profile": {
    "type": "user_id",
    "value": "string"
  }
}

Ответы

  • 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.

Ключ: secretKey · Права: loyalty.write

Параметры

  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

  • profileLoyaltyProfileRefобязательно
  • codestringобязательно

    длина: ≤ 16

Пример тела запроса
{
  "profile": {
    "type": "user_id",
    "value": "string"
  },
  "code": "string"
}

Ответы

  • 200Counted before

    LoyaltyReferral

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

      значения: "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.

      значения: "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.

Ключ: secretKey · Права: loyalty.write

Параметры

  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

  • profileLoyaltyProfileRefобязательно
  • pointsintegerобязательно

    диапазон: ≥ 1

  • cart_idstringобязательно

    длина: ≤ 255

  • amountnumber

    диапазон: ≥ 0

Пример тела запроса
{
  "profile": {
    "type": "user_id",
    "value": "string"
  },
  "points": 1,
  "cart_id": "string",
  "amount": 0
}

Ответы

  • 201Created

    LoyaltyRedemption

    • idstring
    • statusstring

      значения: "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.

Ключ: secretKey · Права: loyalty.write

Параметры

  • redemptionв путиstringобязательно
    Redemption id from the hold response.
  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

  • order_idstringобязательно

    длина: ≤ 255

Пример тела запроса
{
  "order_id": "string"
}

Ответы

  • 200OK

    LoyaltyRedemption

    • idstring
    • statusstring

      значения: "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).

Ключ: secretKey · Права: loyalty.write

Параметры

  • redemptionв путиstringобязательно
    Redemption id from the hold response.

Ответы

  • 200OK

    LoyaltyRedemption

    • idstring
    • statusstring

      значения: "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.

Ключ: secretKey · Права: loyalty.write

Параметры

  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

  • profileLoyaltyProfileRefобязательно
  • pointsintegerобязательно
    Positive — add, negative — take off
  • reasonstringобязательно

    длина: ≤ 500

Пример тела запроса
{
  "profile": {
    "type": "user_id",
    "value": "string"
  },
  "points": 0,
  "reason": "string"
}

Ответы

  • 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.

Ключ: secretKey · Права: promo.read

Ответы

  • 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.

Ключ: secretKey · Права: promo.read

Параметры

  • keyв путиstringобязательно
    Pool key — the name used in templates: {{ promo_code('summer') }}.

    шаблон: ^[a-z0-9_]{1,64}$

Ответы

  • 200OK

    PromoPool

    • keystringобязательно
    • namestringобязательно
    • typestringобязательно
      shared — one code for everyone; unique — a separate code for every profile.

      значения: "shared", "unique"

    • statusstringобязательно

      значения: "active", "paused"

    • activebooleanобязательно
      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_profileintegerобязательно
      How many codes of the pool one profile can receive.
    • statsobjectобязательно
      • 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.

Ключ: secretKey · Права: promo.read

Параметры

  • keyв путиstringобязательно
    Pool key — the name used in templates: {{ promo_code('summer') }}.

    шаблон: ^[a-z0-9_]{1,64}$

  • sinceв строке запросаstring
    Cursor from the previous response.
  • limitв строке запросаinteger

    по умолчанию: 500 · диапазон: 1–1000

Ответы

  • 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.

Ключ: secretKey · Права: promo.write

Параметры

  • keyв путиstringобязательно
    Pool key — the name used in templates: {{ promo_code('summer') }}.

    шаблон: ^[a-z0-9_]{1,64}$

  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

  • countinteger

    диапазон: 1–50000

  • codesstring[]

    элементов: ≤ 100000

Пример тела запроса
{
  "count": 1,
  "codes": [
    "string"
  ]
}

Ответы

  • 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).

Ключ: secretKey · Права: promo.write

Параметры

  • keyв путиstringобязательно
    Pool key — the name used in templates: {{ promo_code('summer') }}.

    шаблон: ^[a-z0-9_]{1,64}$

  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

Пример тела запроса
{
  "profile": {
    "type": "user_id",
    "value": "string"
  }
}

Ответы

  • 200Already issued

    PromoCode

    • poolstring
      Pool key.
    • codestringобязательно
    • statusstringобязательно

      значения: "available", "issued", "used", "shared"

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

    PromoCode

    • poolstring
      Pool key.
    • codestringобязательно
    • statusstringобязательно

      значения: "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

      значения: "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.

Ключ: secretKey · Права: promo.read

Параметры

  • codeв путиstringобязательно
    Promo code, case-insensitive.

    длина: ≤ 64

Ответы

  • 200OK

    Все поля 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.

Ключ: secretKey · Права: promo.read

Параметры

  • typeв путиstringобязательно

    значения: "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"

  • valueв путиstringобязательно
    Normalized like at ingestion (lower-case email, E.164 phone).

Ответы

  • 200OK
    • dataPromoCode[]

      Все поля 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.

Ключ: secretKey · Права: messages.send

Параметры

  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

MessageSendInput

  • identityIdentityRefобязательно
    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.*.

    ключей: ≤ 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.

    элементов: 2–5

Пример тела запроса
{
  "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"
      }
    }
  ]
}

Ответы

  • 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.

Ключ: secretKey · Права: messages.send

Параметры

  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

StoreEmailInput

  • tostring (email)обязательно
    Recipient address. The profile is found by this email or created.

    длина: ≤ 254

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

    длина: ≤ 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.

    длина: ≤ 1000000

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

    длина: ≤ 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.

    длина: ≤ 100

  • kindstringобязательно
    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).

    шаблон: ^[a-z0-9_]{1,40}$

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

    длина: ≤ 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.

    элементов: ≤ 5

    • namestringобязательно

      длина: ≤ 200

    • typestringобязательно

      значения: "application/pdf", "image/png", "image/jpeg", "image/gif", "text/plain", "text/csv", "text/calendar"

    • contentstring (byte)обязательно
      File contents in base64.
Пример тела запроса
{
  "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"
    }
  }
}

Ответы

  • 202Queued

    StoreEmailStatus

    Все поля 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.

Ключ: secretKey · Права: messages.send

Ответы

  • 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.

Ключ: secretKey · Права: messages.send

Параметры

  • cascadeв путиstring (uuid)обязательно
    Cascade id (UUID) from the send response.

Ответы

  • 200OK

    CascadeStatus

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

      значения: "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).

Ключ: secretKey · Права: messages.send

Параметры

  • messageв путиstring (uuid)обязательно
    Message id (UUID) from the send response.

Ответы

  • 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.

      значения: "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.

Ключ: secretKey · Права: chats.read

Параметры

  • statusв строке запросаstring
    open — waiting for an answer.

    значения: "open", "waiting", "closed"

  • channelв строке запросаstring

    значения: "web", "telegram", "whatsapp", "viber", "max", "vk", "instagram", "messenger", "email"

  • profile_typeв строке запросаstring
    Identity type of the customer; together with profile_value.

    значения: "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_valueв строке запросаstring
    Identity value of the customer; together with profile_type.

    длина: ≤ 255

  • limitв строке запросаinteger

    по умолчанию: 50 · диапазон: 1–200

  • cursorв строке запросаstring

Ответы

  • 200OK
    • dataConversation[]обязательно
    • next_cursorstring | nullобязательно
      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.

Ключ: secretKey · Права: chats.read

Параметры

  • conversationв путиstring (uuid)обязательно
    Conversation id (UUID).
  • limitв строке запросаinteger
    How many latest messages to return.

    по умолчанию: 100 · диапазон: 1–500

Ответы

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.

Ключ: secretKey · Права: chats.reply

Параметры

  • conversationв путиstring (uuid)обязательно
    Conversation id (UUID).
  • Idempotency-Keyзаголовокstring
    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.

    длина: ≤ 255

Тело запросаобязательно

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

    длина: 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.

    элементов: ≤ 10

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

    элементов: ≤ 4

Пример тела запроса
{
  "body": "string",
  "buttons": [
    "string"
  ],
  "products": [
    "string"
  ]
}

Ответы

  • 201Created

    ConversationMessage

    • idintegerобязательно
    • authorstringобязательно
      visitor — the customer; operator — an answer from the inbox or the API; system — assignment, closing and reopening (see action).

      значения: "visitor", "operator", "system"

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

      значения: "inbox", "api", null

    • api_keystring | null
      Name of the API key that answered or closed the conversation.
    • bodystringобязательно
      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

      значения: "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)обязательно
    • 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

        значения: "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

        значения: "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.

Ключ: secretKey · Права: chats.reply

Параметры

  • conversationв путиstring (uuid)обязательно
    Conversation id (UUID).

Ответы

  • 200OK

    Conversation

    • idstring (uuid)обязательно
    • profile_idintegerобязательно
    • channelstringобязательно
      web — the website chat; messengers need the chat_messengers plan feature.

      значения: "web", "telegram", "whatsapp", "viber", "max", "vk", "instagram", "messenger", "email"

    • statusstringобязательно
      open — the customer wrote last and waits for an answer; waiting — answered, waiting for the customer; closed.

      значения: "open", "waiting", "closed"

    • assignedbooleanобязательно
      An operator is responsible for the conversation.
    • unread_countintegerобязательно
      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.

      диапазон: 1–5

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

      значения: "visitor", "operator", "system", null

    • first_reply_atstring (date-time) | null
    • created_atstring (date-time)обязательно
    • 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.

Ключ: secretKey · Права: chats.manage

Тело запросаобязательно

  • urlstring (uri)обязательно
    HTTPS address of the store MCP server

    длина: ≤ 2048

  • keystringобязательно
    Bearer key the platform sends to the store

    длина: 32–500

  • namestring

    длина: ≤ 120

  • platformstring

    значения: "woocommerce", "magento", "bitrix", "sdk", "custom"

Пример тела запроса
{
  "url": "https://example.com",
  "key": "string",
  "name": "string",
  "platform": "woocommerce"
}

Ответы

  • 200Updated

    StoreMcpServer

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

      значения: "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

      значения: "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.

Ключ: secretKey · Права: chats.manage

Тело запросаобязательно

  • urlstringобязательно

    длина: ≤ 2048

Пример тела запроса
{
  "url": "string"
}

Ответы

  • 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.

Ключ: writeKey

Параметры

  • uidв путиstringобязательно
    Form uid from the site code.

    длина: ≤ 16

Тело запросаобязательно

  • anonymousIdstringобязательно

    длина: ≤ 255

  • userIdstring

    длина: ≤ 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.

    длина: ≤ 128

  • valuesobjectобязательно
    Form fields: email, phone, first_name, last_name, birthday (YYYY-MM-DD) and consent (boolean).
  • languagestring

    длина: ≤ 35

  • pagestring

    длина: ≤ 2000

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

    значения: "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.

    длина: ≤ 32

Пример тела запроса
{
  "anonymousId": "string",
  "userId": "string",
  "userHash": "string",
  "values": {},
  "language": "string",
  "page": "string",
  "website": "string",
  "variant": "a",
  "play": "string"
}

Ответы

  • 201Accepted
    • statusstringобязательно
      pending — waiting for the confirmation link; accepted — applied to the profile.

      значения: "pending", "accepted"

    • messagestringобязательно
      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

        значения: "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.

Ключ: writeKey

Параметры

  • uidв путиstringобязательно
    Form uid from the site code.

    длина: ≤ 16

Тело запросаобязательно

  • anonymousIdstringобязательно

    длина: ≤ 255

  • userIdstring

    длина: ≤ 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.

    длина: ≤ 128

  • languagestring

    длина: ≤ 35

Пример тела запроса
{
  "anonymousId": "string",
  "userId": "string",
  "userHash": "string",
  "language": "string"
}

Ответы

  • 201Drawn
    • playstring | null
      Token for the submission; null when this draw has already been claimed.
    • 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

        значения: "promo", "text", "none"

      • labelstring
      • textstring
    • playedbooleanобязательно
      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.

Ключ: writeKey

Параметры

  • languageв строке запросаstring
    Visitor language (BCP 47).

    длина: ≤ 35

  • anonymousIdв строке запросаstring
    Visitor id: forms shown to segment members are filtered by the visitor's profile.

    длина: ≤ 255

Ответы

  • 200OK
    • formsobject[]обязательно
      • uidstring
      • kindstring

        значения: "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

Схемы

Error

  • messagestringобязательно

ValidationError

  • messagestringобязательно
  • errorsobjectобязательно

IdentityRef

  • typestringобязательно

    значения: "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"

  • valuestringобязательно

    длина: ≤ 255

IdentitiesInput

  • identitiesIdentityRef[]обязательно

    элементов: 1–1000

Message

  • typestring

    значения: "track", "identify", "page", "screen", "alias"

  • messageIdstring

    длина: ≤ 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.

    длина: ≤ 128

  • previousIdstring | integer
  • eventstring

    длина: ≤ 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.

    элементов: ≤ 20

    • channelstringобязательно

      шаблон: ^[a-z0-9_]{1,64}$ · пример: "email"

    • topicstring
      Subscription topic; the whole channel if omitted.

      шаблон: ^[a-z0-9_-]{1,64}$

    • statusstringобязательно

      значения: "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

    значения: "dynamic", "static"

  • realtimeboolean
  • schedule_minutesinteger | null
  • statusstring

    значения: "pending", "computing", "ready", "failed"

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

SegmentDetail

Все поля Segment:

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

SegmentInput

  • namestringобязательно

    длина: ≤ 120

  • descriptionstring | null
  • typestringобязательно

    значения: "dynamic", "static"

  • realtimeboolean
  • schedule_minutesinteger

    значения: 15, 30, 60, 180, 360, 720, 1440

  • rulesobject

SegmentPatch

  • namestring

    длина: ≤ 120

  • descriptionstring | null
  • realtimeboolean
  • schedule_minutesinteger
  • rulesobject

Journey

  • idinteger
  • namestring
  • descriptionstring | null
  • statusstring

    значения: "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.

    значения: "pending", "approved", "returned"

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

JourneyDetail

Все поля Journey:

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

JourneyInput

  • namestringобязательно

    длина: ≤ 120

  • descriptionstring | null
  • graphobject
    • nodesarray

      элементов: ≤ 200

    • edgesarray

      элементов: ≤ 400

  • entryobject

JourneyPatch

  • namestring

    длина: ≤ 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[]обязательно
    Members of any of these segments get the campaign.

    элементов: ≤ 10

  • exclude_segment_idsinteger[]
    Members of these segments are excluded.

    элементов: ≤ 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

  • keystringобязательно

    шаблон: ^[a-z0-9_]{1,32}$

  • template_idinteger | null
    Message template of the campaign channel.
  • percentintegerобязательно
    Share of the audience (or of the A/B test share); all variants add up to 100.

    диапазон: 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

    значения: "test", "auto" · по умолчанию: "test"

  • test_percentinteger

    диапазон: 5–50

  • metricstringобязательно

    значения: "opened", "clicked", "goal"

  • waitobject
    • amountinteger

      диапазон: 1–72

    • unitstring

      значения: "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.
  • typestringобязательно

    значения: "now", "at", "recurring"

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

    пример: "2026-11-01T10:00"

  • repeatstring

    значения: "daily", "weekly", "monthly"

  • timestring

    пример: "10:00"

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

    диапазон: 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.
  • eventstringобязательно
  • withinobjectобязательно
    • amountinteger

      диапазон: 1–90

    • unitstring

      значения: "hour", "day"

Campaign

  • idinteger
  • namestring
  • descriptionstring | null
  • statusstring

    значения: "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.

    значения: "pending", "approved", "returned"

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

CampaignInput

  • namestringобязательно

    длина: ≤ 120

  • descriptionstring | null
  • integration_idinteger | null
    Channel integration; the template of every variant must belong to its channel.
  • audienceCampaignAudienceобязательно
  • variantsCampaignVariant[]обязательно

    элементов: 1–5

  • scheduleCampaignScheduleобязательно
  • rate_per_minuteinteger | null

    диапазон: 10–100000

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

    значения: "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

    значения: "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

    значения: "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

      элементов: 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

  • idstringобязательно
    Product id on the site: product_id in events.

    длина: ≤ 128

  • namestringобязательно

    длина: ≤ 500

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

    диапазон: ≥ 0

  • old_pricenumber

    диапазон: ≥ 0

  • currencystring

    длина: 3–3

  • availableboolean

    по умолчанию: 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.

    диапазон: ≥ 0

  • category_idsstring[]
    Leaf category first.

    элементов: ≤ 10

  • brandstring

    длина: ≤ 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.

    длина: ≤ 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.

    ключей: ≤ 20

MessageTemplate

  • idinteger
  • namestring
  • channelstring

    пример: "email"

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

    длина: ≤ 16 · пример: "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

  • namestringобязательно

    длина: ≤ 120

  • channel_keystringобязательно
    Channel of the template; cannot be changed later.
  • topicstring

    по умолчанию: "marketing" · длина: ≤ 64 · шаблон: ^[a-z0-9_-]+$

  • transactionalboolean

    по умолчанию: false

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

    длина: ≤ 16 · пример: "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.

    ключей: ≤ 50

AnalyticsReportType

string

значения: "report", "funnel", "retention", "paths", "revenue", "traffic", "attribution", "ropo", "assistants"

AnalyticsPeriod

Один из вариантов:

    • lastintegerобязательно
      Last N days including today, in the project timezone

      значения: 7, 14, 30, 90, 180, 365

    • fromstring (date)обязательно
    • tostring (date)обязательно
    Dates in the project timezone, up to 731 days

PropertyFilter

  • keystringобязательно
    Property key from the event catalog
  • operatorstringобязательно
    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.

Объект с произвольными ключами.

Breakdown

  • sourcestringобязательно

    значения: "property", "context"

  • keystringобязательно
    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.

    значения: 5, 10 · по умолчанию: 10

AnalyticsInterval

string

значения: "day", "week", "month"

ReportQuery

FunnelQuery

  • stepsobject[]обязательно

    элементов: 2–10

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

      диапазон: ≥ 1

    • unitstring

      значения: "minute", "hour", "day"

  • orderstring

    значения: "sequential", "strict"

  • profilesProfileRules
  • breakdownBreakdown

RetentionQuery

PathQuery

  • eventstringобязательно
  • directionstring

    значения: "after", "before"

  • stepsinteger

    диапазон: 1–5

  • gap_minutesinteger

    диапазон: 1–1440

  • excludestring[]

    элементов: ≤ 20

  • profilesProfileRules

RevenueQuery

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

    значения: "week", "month"

  • ltv_periodsinteger

    диапазон: 1–12

  • profilesProfileRules

TrafficQuery

AttributionQuery

ReportResult

  • definitionobjectобязательно
    Normalized definition
  • periodobjectобязательно
    • fromstring (date)
    • tostring (date)
  • bucketsstring (date)[]обязательно
  • seriesobject[]обязательно
    Per series: index, total, values per bucket, previous period, breakdown

FunnelResult

  • definitionobjectобязательно
    Normalized definition
  • periodobjectобязательно
    • fromstring (date)
    • tostring (date)
  • stepsobject[]обязательно
    Per step: event, reached, from_start, from_previous, median_seconds, avg_seconds
  • breakdownobject[]обязательно
    Per breakdown value: value, steps (reached per step)
  • time_samplenumber
    Share of profiles used for time between steps

RetentionResult

  • definitionobjectобязательно
    Normalized definition
  • periodobjectобязательно
    • fromstring (date)
    • tostring (date)
  • cohortsobject[]обязательно
    Per cohort: date, size, values (returned per period, null — not yet), open (period still running)
  • averageobject[]обязательно
    Per period: period, rate, profiles

PathResult

  • definitionobjectобязательно
    Normalized definition
  • periodobjectобязательно
    • fromstring (date)
    • tostring (date)
  • totalintegerобязательно
  • nodesobject[]обязательно
  • linksobject[]обязательно
  • pathsobject[]обязательно
    Most frequent paths: events, profiles
  • truncatedboolean

RevenueResult

  • definitionobjectобязательно
    Normalized definition
  • periodobjectобязательно
    • fromstring (date)
    • tostring (date)
  • currencystring | null
  • other_currency_ordersinteger
  • summaryobjectобязательно
  • seriesobjectобязательно
  • ltvobjectобязательно
  • productsobject[]обязательно
  • categoriesobject[]обязательно

TrafficResult

  • definitionobjectобязательно
    Normalized definition
  • periodobjectобязательно
    • fromstring (date)
    • tostring (date)
  • currencystring | null
  • purchasesboolean
  • summaryobjectобязательно
  • rowsobject[]обязательно
  • row_countinteger
  • chartobjectобязательно

AttributionResult

  • definitionobjectобязательно
    Normalized definition
  • periodobjectобязательно
    • fromstring (date)
    • tostring (date)
  • currencystring | null
  • summaryobjectобязательно
  • channelsobject[]обязательно
    Per channel: channel, clicks, touched_orders, revenue and orders by model
  • itemsobject[]обязательно
    Per campaign, journey, message channel or widget
  • chartobject

SavedReport

  • idintegerобязательно
  • namestringобязательно
  • typeAnalyticsReportTypeобязательно
  • created_atstring (date-time)обязательно
  • updated_atstring (date-time)обязательно

SavedReportDetail

Все поля SavedReport:

  • definitionobjectобязательно
  • viewobjectобязательно
    Page view settings: chart type, metric

SavedReportInput

  • namestringобязательно

    длина: ≤ 120

  • typeAnalyticsReportTypeобязательно
  • definitionobjectобязательно
    Definition of the report type — see the run operations
  • viewobject

SavedReportPatch

  • namestring

    длина: ≤ 120

  • definitionobject
  • viewobject

Dashboard

  • idintegerобязательно
  • namestringобязательно
  • layoutobject[]обязательно

    элементов: ≤ 24

    • report_idintegerобязательно
    • sizestring

      значения: "half", "full"

  • periodAnalyticsPeriodобязательно
  • mainbooleanобязательно
    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)обязательно
  • updated_atstring (date-time)обязательно

DashboardInput

  • namestringобязательно

    длина: ≤ 120

  • layoutobject[]

    элементов: ≤ 24

    • report_idintegerобязательно
    • sizestring

      значения: "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

    длина: ≤ 120

  • layoutobject[]

    элементов: ≤ 24

    • report_idintegerобязательно
    • sizestring

      значения: "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

  • typestringобязательно

    значения: "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"

  • valuestringобязательно

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

    значения: "held", "confirmed", "cancelled", "expired"

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

LoyaltyTransaction

  • idinteger
  • typestring

    значения: "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.

    значения: "friend", "referrer", null

PromoPool

  • keystringобязательно
  • namestringобязательно
  • typestringобязательно
    shared — one code for everyone; unique — a separate code for every profile.

    значения: "shared", "unique"

  • statusstringобязательно

    значения: "active", "paused"

  • activebooleanобязательно
    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_profileintegerобязательно
    How many codes of the pool one profile can receive.
  • statsobjectобязательно
    • totalinteger
    • availableinteger
    • issuedinteger
    • usedinteger
    • usesinteger
    • revenuenumber
      Sum of the orders with codes of the pool.

PromoCode

  • poolstring
    Pool key.
  • codestringобязательно
  • statusstringобязательно

    значения: "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.

    значения: "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.
  • identityIdentityRefобязательно
    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.*.

    ключей: ≤ 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.

    элементов: 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.

    значения: "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_idintegerобязательно
  • template_idintegerобязательно
    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).

    значения: "sent", "delivered", "opened" · по умолчанию: "sent"

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

      диапазон: 1–3650

    • unitstring

      значения: "minute", "hour", "day", "week"

CascadeStatus

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

    значения: "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

    значения: "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

      значения: "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

      значения: "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

    значения: "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)обязательно
  • profile_idintegerобязательно
  • channelstringобязательно
    web — the website chat; messengers need the chat_messengers plan feature.

    значения: "web", "telegram", "whatsapp", "viber", "max", "vk", "instagram", "messenger", "email"

  • statusstringобязательно
    open — the customer wrote last and waits for an answer; waiting — answered, waiting for the customer; closed.

    значения: "open", "waiting", "closed"

  • assignedbooleanобязательно
    An operator is responsible for the conversation.
  • unread_countintegerобязательно
    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.

    диапазон: 1–5

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

    значения: "visitor", "operator", "system", null

  • first_reply_atstring (date-time) | null
  • created_atstring (date-time)обязательно
  • closed_atstring (date-time) | null

ConversationMessage

  • idintegerобязательно
  • authorstringобязательно
    visitor — the customer; operator — an answer from the inbox or the API; system — assignment, closing and reopening (see action).

    значения: "visitor", "operator", "system"

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

    значения: "inbox", "api", null

  • api_keystring | null
    Name of the API key that answered or closed the conversation.
  • bodystringобязательно
    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

    значения: "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)обязательно
  • 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

      значения: "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

      значения: "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

Все поля Conversation:

StoreEmailInput

  • tostring (email)обязательно
    Recipient address. The profile is found by this email or created.

    длина: ≤ 254

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

    длина: ≤ 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.

    длина: ≤ 1000000

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

    длина: ≤ 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.

    длина: ≤ 100

  • kindstringобязательно
    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).

    шаблон: ^[a-z0-9_]{1,40}$

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

    длина: ≤ 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.

    элементов: ≤ 5

    • namestringобязательно

      длина: ≤ 200

    • typestringобязательно

      значения: "application/pdf", "image/png", "image/jpeg", "image/gif", "text/plain", "text/csv", "text/calendar"

    • contentstring (byte)обязательно
      File contents in base64.

StoreEmailStatus

Все поля 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_idstringобязательно

    длина: ≤ 100

  • numberstring | null
    Number shown to the customer; order_id when empty.

    длина: ≤ 100

  • urlstring (uri) | null
    Order page for the customer.
  • created_atstring (date-time) | null
  • currencystringобязательно

    шаблон: ^[A-Za-z]{3}$

  • amountnumberобязательно
    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[]

    элементов: ≤ 100

    • product_idstring | null
    • variant_idstring | null
    • skustring | null
    • product_namestringобязательно

      длина: ≤ 300

    • quantitynumberобязательно
    • pricenumberобязательно
    • 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».

      длина: ≤ 500

  • shipping_addressobject | null
    • namestring | null

      длина: ≤ 200

    • companystring | null

      длина: ≤ 200

    • address1string | null

      длина: ≤ 200

    • address2string | null

      длина: ≤ 200

    • citystring | null

      длина: ≤ 200

    • regionstring | null

      длина: ≤ 200

    • postcodestring | null

      длина: ≤ 200

    • countrystring | null

      длина: ≤ 200

    • phonestring | null

      длина: ≤ 200

  • billing_addressobject | null
    • namestring | null

      длина: ≤ 200

    • companystring | null

      длина: ≤ 200

    • address1string | null

      длина: ≤ 200

    • address2string | null

      длина: ≤ 200

    • citystring | null

      длина: ≤ 200

    • regionstring | null

      длина: ≤ 200

    • postcodestring | null

      длина: ≤ 200

    • countrystring | null

      длина: ≤ 200

    • phonestring | null

      длина: ≤ 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

    значения: "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.

    пример: "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

      пример: "email"

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

      пример: "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

      пример: "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.

    значения: "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

  • idstringобязательно
    Store id — the value of store_id in offline checks.

    длина: ≤ 128

  • namestringобязательно

    длина: ≤ 200

  • citystring | null

    длина: ≤ 120

  • addressstring | null

    длина: ≤ 300

RopoQuery

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

    значения: 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

  • definitionobjectобязательно
    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, %

    диапазон: 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

      элементов: 2–2

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

      элементов: 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

      значения: "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

  • readybooleanобязательно
    No errors: the launch will pass.
  • clearbooleanобязательно
    No errors and no warnings.
  • checksobject[]обязательно
    • keystringобязательно
      config, archived, quota, sending_domain, integration, untranslated, template_error, unsubscribe, deliverability, segment_pending, segment_empty, segment_broad, goal_missing, goal_unseen, goal_window
    • levelstringобязательно

      значения: "error", "warning", "info"

    • messagestringобязательно
      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[]

    элементов: ≤ 1000

    • namestringобязательно
      Event name (system $… events are not allowed)

      длина: ≤ 255

    • labelstring | null

      длина: ≤ 255

    • descriptionstring | null

      длина: ≤ 1000

    • propertiesobject[]

      элементов: ≤ 200

      • keystringобязательно

        длина: ≤ 255

      • typestringобязательно

        значения: "string", "number", "boolean", "datetime", "list", "object"

      • requiredboolean

        по умолчанию: false

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

        элементов: ≤ 100

        Один из вариантов:

      • descriptionstring | null

        длина: ≤ 1000

EventSchemaViolation

  • kindstring

    значения: "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.

    значения: "pending", "approved", "returned"

  • approved_bystring
  • approved_atstring (date-time)
  • changedboolean
    Approved, but changed since approval: launch will send it back to review.
  • historyobject[]
    • actionstring

      значения: "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

  • definitionobjectобязательно
    Normalized definition
  • periodobjectобязательно
    • fromstring (date)
    • tostring (date)
  • currencystring | null
  • purchasesboolean
  • attribution_daysinteger
  • summaryobjectобязательно
    current and previous period: requests, searches, product_clicks, carts, cart_clicks, assistant_orders, visits, visitors, orders, revenue
  • assistantsobject[]обязательно
  • chartobjectобязательно
    buckets and per assistant requests and visits by bucket
  • queriesobject[]обязательно
    • querystring
    • countinteger
    • emptyinteger
      Searches without results
  • productsobject[]обязательно
    • idstring
    • namestring | null
    • requestsinteger
    • clicksinteger