API reference
Event collection, profiles, segments, journeys and campaigns — an OpenAPI 3.1 specification.
Overview
{"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.Keys
writeKeyhttp bearercdp_wk_…: ingestion only. Also accepted as Basic auth user orwriteKeybody field.secretKeyhttp bearercdp_sk_…: server-side only, permissions chosen when the key is created.
Ingest
Track an event
post/track
Request bodyrequired
typestringvalues:
"track", "identify", "page", "screen", "alias"messageIdstringlength:
≤ 100anonymousIdstring | integeruserIdstring | integeruserHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.length:
≤ 128previousIdstring | integereventstringlength:
≤ 200namestringpropertiesobjecttraitsobjectcontextobjectconsentsobject[]identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.items:
≤ 20channelstringrequiredpattern:
^[a-z0-9_]{1,64}$· example:"email"topicstringSubscription topic; the whole channel if omitted.pattern:
^[a-z0-9_-]{1,64}$statusstringrequiredvalues:
"subscribed", "unsubscribed"
timestampstring (date-time)
Request body example
{
"type": "track",
"messageId": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"previousId": "string",
"event": "string",
"name": "string",
"properties": {},
"traits": {},
"context": {},
"consents": [
{
"channel": "email",
"topic": "string",
"status": "subscribed"
}
],
"timestamp": "2026-01-01T10:00:00Z"
}Responses
202Accepted for asynchronous processing
acceptedintegerduplicatesinteger
- 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
Request bodyrequired
typestringvalues:
"track", "identify", "page", "screen", "alias"messageIdstringlength:
≤ 100anonymousIdstring | integeruserIdstring | integeruserHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.length:
≤ 128previousIdstring | integereventstringlength:
≤ 200namestringpropertiesobjecttraitsobjectcontextobjectconsentsobject[]identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.items:
≤ 20channelstringrequiredpattern:
^[a-z0-9_]{1,64}$· example:"email"topicstringSubscription topic; the whole channel if omitted.pattern:
^[a-z0-9_-]{1,64}$statusstringrequiredvalues:
"subscribed", "unsubscribed"
timestampstring (date-time)
Request body example
{
"type": "track",
"messageId": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"previousId": "string",
"event": "string",
"name": "string",
"properties": {},
"traits": {},
"context": {},
"consents": [
{
"channel": "email",
"topic": "string",
"status": "subscribed"
}
],
"timestamp": "2026-01-01T10:00:00Z"
}Responses
202Accepted for asynchronous processing
acceptedintegerduplicatesinteger
- 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
Request bodyrequired
typestringvalues:
"track", "identify", "page", "screen", "alias"messageIdstringlength:
≤ 100anonymousIdstring | integeruserIdstring | integeruserHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.length:
≤ 128previousIdstring | integereventstringlength:
≤ 200namestringpropertiesobjecttraitsobjectcontextobjectconsentsobject[]identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.items:
≤ 20channelstringrequiredpattern:
^[a-z0-9_]{1,64}$· example:"email"topicstringSubscription topic; the whole channel if omitted.pattern:
^[a-z0-9_-]{1,64}$statusstringrequiredvalues:
"subscribed", "unsubscribed"
timestampstring (date-time)
Request body example
{
"type": "track",
"messageId": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"previousId": "string",
"event": "string",
"name": "string",
"properties": {},
"traits": {},
"context": {},
"consents": [
{
"channel": "email",
"topic": "string",
"status": "subscribed"
}
],
"timestamp": "2026-01-01T10:00:00Z"
}Responses
202Accepted for asynchronous processing
acceptedintegerduplicatesinteger
- 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
Request bodyrequired
typestringvalues:
"track", "identify", "page", "screen", "alias"messageIdstringlength:
≤ 100anonymousIdstring | integeruserIdstring | integeruserHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.length:
≤ 128previousIdstring | integereventstringlength:
≤ 200namestringpropertiesobjecttraitsobjectcontextobjectconsentsobject[]identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.items:
≤ 20channelstringrequiredpattern:
^[a-z0-9_]{1,64}$· example:"email"topicstringSubscription topic; the whole channel if omitted.pattern:
^[a-z0-9_-]{1,64}$statusstringrequiredvalues:
"subscribed", "unsubscribed"
timestampstring (date-time)
Request body example
{
"type": "track",
"messageId": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"previousId": "string",
"event": "string",
"name": "string",
"properties": {},
"traits": {},
"context": {},
"consents": [
{
"channel": "email",
"topic": "string",
"status": "subscribed"
}
],
"timestamp": "2026-01-01T10:00:00Z"
}Responses
202Accepted for asynchronous processing
acceptedintegerduplicatesinteger
- 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
Request bodyrequired
typestringvalues:
"track", "identify", "page", "screen", "alias"messageIdstringlength:
≤ 100anonymousIdstring | integeruserIdstring | integeruserHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.length:
≤ 128previousIdstring | integereventstringlength:
≤ 200namestringpropertiesobjecttraitsobjectcontextobjectconsentsobject[]identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.items:
≤ 20channelstringrequiredpattern:
^[a-z0-9_]{1,64}$· example:"email"topicstringSubscription topic; the whole channel if omitted.pattern:
^[a-z0-9_-]{1,64}$statusstringrequiredvalues:
"subscribed", "unsubscribed"
timestampstring (date-time)
Request body example
{
"type": "track",
"messageId": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"previousId": "string",
"event": "string",
"name": "string",
"properties": {},
"traits": {},
"context": {},
"consents": [
{
"channel": "email",
"topic": "string",
"status": "subscribed"
}
],
"timestamp": "2026-01-01T10:00:00Z"
}Responses
202Accepted for asynchronous processing
acceptedintegerduplicatesinteger
- 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
Request bodyrequired
items:
≤ 500
Request body example
{
"batch": [
{
"type": "track",
"messageId": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"previousId": "string",
"event": "string",
"name": "string",
"properties": {},
"traits": {},
"context": {},
"consents": [
{
"channel": "email",
"topic": "string",
"status": "subscribed"
}
],
"timestamp": "2026-01-01T10:00:00Z"
}
]
}Responses
202Accepted for asynchronous processing
acceptedintegerduplicatesinteger
- 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
Responses
Tracker module settings in one request
get/site/config
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.Parameters
languagequerystringVisitor language (BCP 47).length:
≤ 35anonymousIdquerystringVisitor id: forms shown to segment members are filtered by the visitor's profile.length:
≤ 255
Responses
200Settings
chatobjectAsGET /chat/configfeedobjectAsGET /feed/configformsobjectAsGET /formssearchobjectAsGET /search/widget;enabled: falsewithout the product search featureaskobjectAsGET /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
Responses
Store a browser push subscription and link it to the visitor
post/push/subscriptions
Request bodyrequired
anonymousIdstringRequired without userIdlength:
≤ 255userIdstringlength:
≤ 255userHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.length:
≤ 128publicKeystringVAPID key the subscription was created withsubscriptionobjectrequiredPushSubscription.toJSON(); the endpoint must belong to a browser push serviceendpointstring (uri)requiredexpirationTimeinteger | nullkeysobjectrequiredp256dhstringrequiredauthstringrequired
Request body example
{
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"publicKey": "string",
"subscription": {
"endpoint": "https://example.com",
"expirationTime": 0,
"keys": {
"p256dh": "string",
"auth": "string"
}
}
}Responses
201Subscription stored; consent is recorded once the profile is processed
subscription_idstring
- 401Missing, invalid or revoked key · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Forget a browser push subscription
delete/push/subscriptions
Request bodyrequired
endpointstringrequired
Request body example
{
"endpoint": "string"
}Responses
200Whether a subscription was removed
deletedboolean
- 401Missing, invalid or revoked key · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Register a mobile app installation from the SDK: push token, notification permission and device details
post/devices
mobile_push identity and consent to the mobile_push channel; otherwise the identity is removed. A token registered by another installation moves here.Request bodyrequired
installationIdstringrequiredRandom id the SDK generates once per installationpattern:
^[A-Za-z0-9_-]{8,64}$anonymousIdstringRequired without userIdlength:
≤ 255userIdstringlength:
≤ 255userHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.length:
≤ 128appobjectrequiredidstringrequirediOS bundle id or Android package nameversionstringbuildstring
osobjectrequirednamestringrequiredvalues:
"ios", "android"versionstring
deviceobjectmanufacturerstringmodelstring
localestringlength:
≤ 35timezonestringIANA time zonelength:
≤ 64pushobjectproviderstringvalues:
"fcm", "apns"tokenstringlength:
≤ 4096enabledbooleanNotifications are allowed by the user
sdkobjectnamestringversionstring
Request body example
{
"installationId": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"app": {
"id": "string",
"version": "string",
"build": "string"
},
"os": {
"name": "ios",
"version": "string"
},
"device": {
"manufacturer": "string",
"model": "string"
},
"locale": "string",
"timezone": "string",
"push": {
"provider": "fcm",
"token": "string",
"enabled": true
},
"sdk": {
"name": "string",
"version": "string"
}
}Responses
200Installation stored
installation_idstringpushbooleanPush 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
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).Request bodyrequired
tokenstringrequiredcdp_token from the notification datalength:
≤ 100eventstringrequiredvalues:
"received", "opened"urlstringThe link opened by the tap (cdp_url)length:
≤ 2000
Request body example
{
"token": "string",
"event": "received",
"url": "string"
}Responses
200Processed
recordedboolean
- 401Missing, invalid or revoked key · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
In-app messages waiting to be shown on this installation
get/in-app/messages
in_app plan feature.Parameters
anonymousIdquerystringrequiredlength:
≤ 255appIdquerystringrequiredBundle id or package nameplatformquerystringrequiredvalues:
"ios", "android"
Responses
200Messages
dataobject[]tokenstringPass it back to /in-app/eventstrigger_eventstring | nullShow after the app tracks this event; null — on the next app openlayoutstringvalues:
"modal", "banner", "fullscreen"positionstringvalues:
"top", "bottom"titlestringbodystringimage_urlstringbutton_textstringbutton_urlstringclose_textstringbackground_colorstringtext_colorstringbutton_colorstringbutton_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.Request bodyrequired
tokenstringrequiredlength:
≤ 100eventstringrequiredvalues:
"shown", "clicked", "dismissed"urlstringlength:
≤ 2000
Request body example
{
"token": "string",
"event": "shown",
"url": "string"
}Responses
200Processed
recordedboolean
- 401Missing, invalid or revoked key · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Message feed of this visitor
get/feed
unread — cards not shown yet. Empty without the feed plan feature.Parameters
anonymousIdquerystringrequiredlength:
≤ 255
Responses
200Feed
dataobject[]tokenstringPass it back to /feed/eventslayoutstringclassic — image on the left, captioned — image on top, banner — image onlyvalues:
"classic", "captioned", "banner"titlestringbodystringimage_urlstringbutton_textstringAbsent — the whole card is the linkbutton_urlstringpinnedbooleanreadbooleanAlready shown in the feedcreated_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
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.Responses
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.Request bodyrequired
tokenstringrequiredlength:
≤ 100eventstringrequiredvalues:
"shown", "clicked", "dismissed"urlstringlength:
≤ 2000
Request body example
{
"token": "string",
"event": "shown",
"url": "string"
}Responses
200Processed
recordedboolean
- 401Missing, invalid or revoked key · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Recommendations
Product recommendations for the site
get/recommendations
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).Parameters
typequerystringrequiredvalues:
"personal", "popular", "trending", "viewed_with", "bought_with", "similar", "recently_viewed", "replenish"limitqueryintegerdefault:
8· range:1–24itemquerystringContext product id (or item[] for a cart) for viewed_with, bought_with, similar.categoryquerystringCategory id for popular and trending.exclude[]querystring[]anonymousIdquerystringimage_widthqueryintegerCard image width (image), px. Variants forare in srcset when imgproxy is configured (ADR-047). default:
480· range:64–1200languagequerystringVisitor language (BCP 47, as in context.locale): product names and links come in the catalog translation for the closest language (ADR-080).length:
≤ 35
Responses
200Recommended products
typestringrequest_idstring (uuid)itemsProductCard[]
- 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}
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).Parameters
uidpathstringrequiredpattern:
^[a-z0-9]{1,16}$item[]querystring[]Context product ids (data-item): page product or cart items.categoryquerystringCategory id (data-category); overrides the widget category.exclude[]querystring[]anonymousIdquerystringlanguagequerystringVisitor language (BCP 47, as in context.locale): the heading, the button and product names come in their translation for the closest language (ADR-078, ADR-080).length:
≤ 35urlquerystringPage address without the domain (path and query): display rules by pages (ADR-139).length:
≤ 2000devicequerystringVisitor device for the display rules (ADR-139).values:
"desktop", "mobile"visitorquerystringNew (first session on the website) or returning visitor for the display rules (ADR-139).values:
"new", "returning"previewquerystringSigned preview mark from the admin panel (cdp_previewin 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 haspreview: trueand norequest_id, views and clicks are not tracked (ADR-139).length:
≤ 200
Responses
200Widget and products
widgetobjectuidstringtypestringstatusstringvalues:
"active", "paused"settingsobjecttitlestringlayoutstringvalues:
"grid", "carousel"columnsintegeraccentstring | nullradiusintegerbuttonstringshowPriceboolean
variantstring | nullpreviewboolean
request_idstring | nullitemsProductCard[]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}
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).Parameters
uidpathstringrequiredpattern:
^[a-z0-9]{1,16}$anonymousIdquerystringlanguagequerystringVisitor language (BCP 47, as in context.locale): the banner texts and the HTML come in their translation for the closest language.length:
≤ 35urlquerystringPage address without the domain (path and query): display rules by pages.length:
≤ 2000devicequerystringVisitor device for the display rules.values:
"desktop", "mobile"visitorquerystringNew (first session on the website) or returning visitor for the display rules.values:
"new", "returning"previewquerystringSigned preview mark from the admin panel (cdp_previewin 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 haspreview: true, views and clicks are not tracked.length:
≤ 200
Responses
200Block content
blockobject | nulluidstringarmstringa–d: default content and its variants; s1–s5: segment rowscontentobjectBanner (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
Responses
200OK
object
Profiles
Get a profile by any identifier
get/profiles/{type}/{value}
profiles.pii.Parameters
typepathstringrequiredvalues:
"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"valuepathstringrequiredNormalized like at ingestion (lower-case email, E.164 phone).
Responses
200OK
idintegertraitsobjectidentitiesobjectfirst_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}
Parameters
typepathstringrequiredvalues:
"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"valuepathstringrequiredNormalized like at ingestion (lower-case email, E.164 phone).
Responses
Profile events, newest first, 50 per page
get/profiles/{type}/{value}/events
Parameters
typepathstringrequiredvalues:
"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"valuepathstringrequiredNormalized like at ingestion (lower-case email, E.164 phone).beforequerystring (date-time)Cursor:next_beforeof the previous page.namequerystring
Responses
Subscribe or unsubscribe a profile
put/profiles/{type}/{value}/consents
Parameters
typepathstringrequiredvalues:
"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"valuepathstringrequiredNormalized like at ingestion (lower-case email, E.164 phone).
Request bodyrequired
channelstringrequiredChannel key, oradsfor the advertising consent: whether the profile's data may be sent to ad platforms (conversions, audiences);adsalways applies to the whole channel.example:
"email"topicstringOmit for the whole channel (all).statusstringrequiredvalues:
"subscribed", "unsubscribed"
Request body example
{
"channel": "email",
"topic": "string",
"status": "subscribed"
}Responses
200OK
object
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Create a Telegram deep link for a profile
post/telegram/link
Request bodyrequired
integrationstringIntegration uid when the project has several bots.
Request body example
{
"identity": {
"type": "user_id",
"value": "string"
},
"integration": "string"
}Responses
200OK
urlstringtokenstringintegrationstring
- 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
Create a Viber bot deep link for a profile
post/viber/link
Request bodyrequired
integrationstringIntegration uid when the project has several Viber bots.
Request body example
{
"identity": {
"type": "user_id",
"value": "string"
},
"integration": "string"
}Responses
200OK
urlstringtokenstringintegrationstring
- 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
Create a MAX bot deep link for a profile
post/max/link
https://max.ru/{bot}?start={token}: opening the bot with it links the MAX user to the profile.Request bodyrequired
integrationstringIntegration uid when the project has several MAX bots.
Request body example
{
"identity": {
"type": "user_id",
"value": "string"
},
"integration": "string"
}Responses
200OK
urlstringtokenstringintegrationstring
- 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
Create a VK community link for a profile
post/vk/link
https://vk.me/{community}?ref={token}: the first message to the community from this link links the VK user to the profile. The same token can be passed as the key of the VK "Allow messages" widget for community group_id.Request bodyrequired
integrationstringIntegration uid when the project has several VK communities.
Request body example
{
"identity": {
"type": "user_id",
"value": "string"
},
"integration": "string"
}Responses
200OK
urlstringtokenstringgroup_idintegerintegrationstring
- 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
Create an Instagram Direct link for a profile
post/instagram/link
https://ig.me/m/{account}?ref={token}: opening the conversation from this link links the Instagram user to the profile.Request bodyrequired
integrationstringIntegration uid when the project has several Instagram accounts.
Request body example
{
"identity": {
"type": "user_id",
"value": "string"
},
"integration": "string"
}Responses
200OK
urlstringtokenstringintegrationstring
- 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
Parameters
typepathstringrequiredvalues:
"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"valuepathstringrequiredNormalized like at ingestion (lower-case email, E.164 phone).languagequerystringLanguage of topic names; the project default when omitted.
Responses
200OK
profile_idintegerlanguagestringLanguage of topic names.example:
"en"channelsobject[]Channels the profile receives or can receive messages in: channels of its consents and messages of the last year, and channels of active integrations it has an address for.keystringexample:
"email"namestringName of the channel in the requested language, lower case as inside a sentence.example:
"email"blockedbooleanHard block (the address does not exist, the bot was stopped): read only.
unsubscribed_allbooleanThe profile unsubscribed from marketing messages in all channels (unsubscribe_allor the preference center): channels without their own subscription stay closed.adsboolean | nullAdvertising consent;null— the project has no ad platform connected, nothing to ask.topicsobject[]Visible subscription topics.keystringexample:
"news"namestringdescriptionstringchannelsobjectChannel key → subscribed (true/false),null— the topic is not offered in this channel.
frequencystring | nullAt most one marketing message per week or month across channels;null— as usual.values:
"weekly", "monthly", nullpaused_untilstring (date-time) | nullMarketing 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
Parameters
typepathstringrequiredvalues:
"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"valuepathstringrequiredNormalized like at ingestion (lower-case email, E.164 phone).
Request bodyrequired
topicsobjectTopic key → channel key → subscribed. Only the given topics and channels change.example:
{"news":{"email":true},"offers":{"email":false}}frequencystring | nullOmit to keep.values:
"weekly", "monthly", nullpaused_untilstring (date-time) | nullPause marketing messages until this time (within a year);nullresumes; omit to keep.unsubscribe_allbooleanUnsubscribe from all marketing messages in every channel, including channels connected or addressable later; other fields are ignored. Subscribing to a channel afterwards (here, byPUT /profiles/{type}/{value}/consentsor by a push permission) opens only that channel.languagestringLanguage of topic names in the response.adsbooleanAdvertising consent: allow (true) or deny (false) sending the profile data to ad platforms. Applies only when the project has an ad platform connected (adsin the response is not null).
Request body example
{
"topics": {
"news": {
"email": true
},
"offers": {
"email": false
}
},
"frequency": "weekly",
"paused_until": "2026-01-01T10:00:00Z",
"unsubscribe_all": true,
"language": "string",
"ads": true
}Responses
200OK
profile_idintegerlanguagestringLanguage of topic names.example:
"en"channelsobject[]Channels the profile receives or can receive messages in: channels of its consents and messages of the last year, and channels of active integrations it has an address for.keystringexample:
"email"namestringName of the channel in the requested language, lower case as inside a sentence.example:
"email"blockedbooleanHard block (the address does not exist, the bot was stopped): read only.
unsubscribed_allbooleanThe profile unsubscribed from marketing messages in all channels (unsubscribe_allor the preference center): channels without their own subscription stay closed.adsboolean | nullAdvertising consent;null— the project has no ad platform connected, nothing to ask.topicsobject[]Visible subscription topics.keystringexample:
"news"namestringdescriptionstringchannelsobjectChannel key → subscribed (true/false),null— the topic is not offered in this channel.
frequencystring | nullAt most one marketing message per week or month across channels;null— as usual.values:
"weekly", "monthly", nullpaused_untilstring (date-time) | nullMarketing 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
wallet_url is null when the project has no Wallet cards (no wallet integration or the plan has no wallet feature).Parameters
typepathstringrequiredvalues:
"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"valuepathstringrequiredNormalized like at ingestion (lower-case email, E.164 phone).languagequerystringLanguage of topic names; the project default when omitted.
Responses
200OK
wallet_urlstring (uri) | nullwallet_url_expires_atstring (date-time) | nullplatformsstring[]passesobject[]platformstringvalues:
"apple", "google"card_numberstringinstalledbooleaninstalled_atstring (date-time) | nullremoved_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
Responses
Products
Create or update products and categories
post/products
Request bodyrequired
items:
≤ 1000categoriesobject[]items:
≤ 1000idstringrequirednamestringrequiredparent_idstring | nulltranslationsobjectCategory name by language (BCP 47 tag → {name}).keys:
≤ 20
Request body example
{
"items": [
{
"id": "string",
"name": "string",
"url": "https://example.com",
"image": "https://example.com",
"price": 0,
"old_price": 0,
"currency": "string",
"available": true,
"stock": 0,
"category_ids": [
"string"
],
"brand": "string",
"description": "string",
"params": {},
"translations": {}
}
],
"categories": [
{
"id": "string",
"name": "string",
"parent_id": "string",
"translations": {}
}
]
}Responses
200Saved
savedintegercategoriesinteger
- 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
Request bodyrequired
idsstring[]requireditems:
1–1000
Request body example
{
"ids": [
"string"
]
}Responses
200Deleted
deletedinteger
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Published reviews of a product
get/reviews
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.Parameters
productquerystringrequiredProduct id from the catalog.length:
≤ 128pagequeryintegerdefault:
1· range:1–1000languagequerystringLanguage of the product name.length:
≤ 35
Responses
200Reviews
productobjectidstringnamestringurlstring | nullimagestring | null
ratingnumber | nullAverage score,nullwithout reviews.countintegerdistributionobjectScore (5…1) → number of reviews.reviewsobject[]idintegerratingintegerrange:
1–5titlestring | nulltextstring | nullauthorstring | nulllanguagestring | nullpublished_atstring (date-time) | null
pageintegermoreboolean
- 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
Request bodyrequired
productstringrequiredProduct id from the catalog.length:
≤ 128ratingintegerrequiredrange:
1–5titlestringlength:
≤ 120textstringlength:
≤ 2000authorstringName shown with the review.length:
≤ 60languagestringlength:
≤ 35publishbooleandefault:
falsedatestring (date-time)Date of a moved review (withpublish).
Request body example
{
"product": "string",
"identity": {
"type": "user_id",
"value": "string"
},
"rating": 1,
"title": "string",
"text": "string",
"author": "string",
"language": "string",
"publish": false,
"date": "2026-01-01T10:00:00Z"
}Responses
201Saved
idintegerstatusstringvalues:
"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.
Request bodyrequired
product_idstringrequiredProduct id in the catalog (id from the feed or the products API)length:
≤ 128questionstringrequiredlength:
≤ 500anonymousIdstringrequiredlength:
≤ 255userIdstringlength:
≤ 255userHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.length:
≤ 128languagestringLanguage of the page (BCP 47); the answer follows the language of the questionlength:
≤ 35asyncbooleanAnswer in the background: 202 withidinstead of waiting for the model (the tracker widget does so)
Request body example
{
"product_id": "string",
"question": "string",
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"language": "string",
"async": true
}Responses
200Answer
answerstringansweredbooleanfalse — the product card and the shop knowledge do not answer the question; the answer says so and suggests asking the staffsourcesobject[]titlestringurlstring | null
202Accepted with `async: true`: the model answers in the background
pendingbooleanidstringToken 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`)
messagestringreasonstring
404No such product
messagestringreasonstring
429Too many questions from this visitor
messagestringreasonstring
502The AI model did not answer
messagestringreasonstring
503AI is not configured on the platform
messagestringreasonstring
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.
Parameters
idquerystringrequiredlength:
40–40
Responses
200Answer
answerstringansweredbooleanfalse — the product card and the shop knowledge do not answer the question; the answer says so and suggests asking the staffsourcesobject[]titlestringurlstring | null
202The model is still answering
pendingboolean
402AI is not available for the project (`reason`)
messagestringreasonstring
404No such result: unknown or expired token
messagestringreasonstring
502The AI model did not answer
messagestringreasonstring
503AI is turned off or not configured on the platform (`reason`)
messagestringreasonstring
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.
Parameters
product_idquerystringrequiredlength:
≤ 128languagequerystringlength:
≤ 35
Responses
200Questions
questionsstring[]
404No such product
messagestringreasonstring
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.
Parameters
languagequerystringlength:
≤ 35
Responses
200Widget settings
enabledbooleanrequiredmodestringvalues:
"block", "chat"chatbooleanOnline chat is on: the block offers to ask the staffsuggestionsbooleanaccentstringexample:
"#4f46e5"radiusintegerrange:
0–24textsobject
Stores
List stores
get/stores
Responses
Create or update stores
post/stores
Request bodyrequired
items:
1–1000
Request body example
{
"items": [
{
"id": "string",
"name": "string",
"city": "string",
"address": "string"
}
]
}Responses
200Saved
savedinteger
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Delete stores
delete/stores
Request bodyrequired
idsstring[]requireditems:
1–1000
Request body example
{
"ids": [
"string"
]
}Responses
200Deleted
deletedinteger
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Catalog
Events seen in the project with their properties
get/catalog/events
Responses
200OK
dataCatalogEvent[]
- 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
Responses
200OK
dataCatalogTrait[]
- 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
enabled — whether incoming events are checked against the schema.Responses
200OK
enabledbooleanCheck incoming events against the schemaeventsobject[]items:
≤ 1000namestringrequiredEvent name (system$…events are not allowed)length:
≤ 255labelstring | nulllength:
≤ 255descriptionstring | nulllength:
≤ 1000propertiesobject[]items:
≤ 200keystringrequiredlength:
≤ 255typestringrequiredvalues:
"string", "number", "boolean", "datetime", "list", "object"requiredbooleandefault:
falsevaluesstring | number[] | nullAllowed values (strings or numbers; only forstringandnumberproperties)items:
≤ 100One of:
descriptionstring | nulllength:
≤ 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
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).Request bodyrequired
enabledbooleanCheck incoming events against the schemaeventsobject[]items:
≤ 1000namestringrequiredEvent name (system$…events are not allowed)length:
≤ 255labelstring | nulllength:
≤ 255descriptionstring | nulllength:
≤ 1000propertiesobject[]items:
≤ 200keystringrequiredlength:
≤ 255typestringrequiredvalues:
"string", "number", "boolean", "datetime", "list", "object"requiredbooleandefault:
falsevaluesstring | number[] | nullAllowed values (strings or numbers; only forstringandnumberproperties)items:
≤ 100One of:
descriptionstring | nulllength:
≤ 1000
Request body example
{
"enabled": true,
"events": [
{
"name": "string",
"label": "string",
"description": "string",
"properties": [
{
"key": "string",
"type": "string",
"required": false,
"values": [
"string"
],
"description": "string"
}
]
}
]
}Responses
200Saved
enabledbooleanCheck incoming events against the schemaeventsobject[]items:
≤ 1000namestringrequiredEvent name (system$…events are not allowed)length:
≤ 255labelstring | nulllength:
≤ 255descriptionstring | nulllength:
≤ 1000propertiesobject[]items:
≤ 200keystringrequiredlength:
≤ 255typestringrequiredvalues:
"string", "number", "boolean", "datetime", "list", "object"requiredbooleandefault:
falsevaluesstring | number[] | nullAllowed values (strings or numbers; only forstringandnumberproperties)items:
≤ 100One of:
descriptionstring | nulllength:
≤ 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
unexpected_value; masked without the profiles.pii permission). Empty while the check is off.Responses
Segments
List segments
get/segments
Parameters
limitqueryintegerdefault:
50· range:1–200cursorquerystring
Responses
Create a segment
post/segments
status. Rules use the same DSL as the segment builder (docs/architecture/segmentation.md).Parameters
Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
namestringrequiredlength:
≤ 120descriptionstring | nulltypestringrequiredvalues:
"dynamic", "static"realtimebooleanschedule_minutesintegervalues:
15, 30, 60, 180, 360, 720, 1440rulesobject
Request body example
{
"name": "string",
"description": "string",
"type": "dynamic",
"realtime": true,
"schedule_minutes": 15,
"rules": {}
}Responses
201Created
- 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}
Parameters
segmentpathintegerrequired
Responses
Update a segment (partial)
patch/segments/{segment}
Parameters
segmentpathintegerrequired
Request bodyrequired
namestringlength:
≤ 120descriptionstring | nullrealtimebooleanschedule_minutesintegerrulesobject
Request body example
{
"name": "string",
"description": "string",
"realtime": true,
"schedule_minutes": 0,
"rules": {}
}Responses
200OK
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Delete a segment
delete/segments/{segment}
Parameters
segmentpathintegerrequired
Responses
- 204Deleted
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Queue a recomputation of a dynamic segment
post/segments/{segment}/compute
Parameters
segmentpathintegerrequired
Responses
Segment members, latest entered first
get/segments/{segment}/members
Parameters
segmentpathintegerrequiredlimitqueryintegerdefault:
50· range:1–200cursorquerystring
Responses
200OK
dataobject[]requiredprofile_idintegerentered_atstring (date-time)
next_cursorstring | nullrequiredPass ascursorto 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
Parameters
segmentpathintegerrequiredIdempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
items:
1–1000
Request body example
{
"identities": [
{
"type": "user_id",
"value": "string"
}
]
}Responses
200OK
addedintegerunknownIdentityRef[]
- 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
Parameters
segmentpathintegerrequired
Request bodyrequired
items:
1–1000
Request body example
{
"identities": [
{
"type": "user_id",
"value": "string"
}
]
}Responses
200OK
removedintegerunknownIdentityRef[]
- 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}
Parameters
segmentpathintegerrequiredtypepathstringrequiredvalues:
"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"valuepathstringrequiredNormalized like at ingestion (lower-case email, E.164 phone).
Responses
Journeys
List journeys
get/journeys
Parameters
limitqueryintegerdefault:
50· range:1–200cursorquerystringstatusquerystringvalues:
"draft", "active", "paused", "archived"
Responses
Create a journey draft
post/journeys
Parameters
Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
namestringrequiredlength:
≤ 120descriptionstring | nullgraphobjectnodesarrayitems:
≤ 200edgesarrayitems:
≤ 400
entryobject
Request body example
{
"name": "string",
"description": "string",
"graph": {
"nodes": [],
"edges": []
},
"entry": {}
}Responses
201Created
All fields of Journey:
draftobjectgraphobjectentryobject
publishedobject | nullgraphobjectentryobject
- 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}
Parameters
journeypathintegerrequired
Responses
200OK
All fields of Journey:
draftobjectgraphobjectentryobject
publishedobject | nullgraphobjectentryobject
- 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}
Parameters
journeypathintegerrequired
Request bodyrequired
namestringlength:
≤ 120descriptionstring | nullgraphobjectentryobject
Request body example
{
"name": "string",
"description": "string",
"graph": {},
"entry": {}
}Responses
200OK
All fields of Journey:
draftobjectgraphobjectentryobject
publishedobject | nullgraphobjectentryobject
- 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
graph.nodes.2.data.template_id.Parameters
journeypathintegerrequired
Responses
200OK
validboolean
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Launch readiness of the draft
get/journeys/{journey}/readiness
Parameters
journeypathintegerrequired
Responses
200OK
readybooleanrequiredNo errors: the launch will pass.clearbooleanrequiredNo errors and no warnings.checksobject[]requiredkeystringrequiredconfig, archived, quota, sending_domain, integration, untranslated, template_error, unsubscribe, deliverability, segment_pending, segment_empty, segment_broad, goal_missing, goal_unseen, goal_windowlevelstringrequiredvalues:
"error", "warning", "info"messagestringrequiredText in the language of the requestpathstringField 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
Parameters
journeypathintegerrequiredIdempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Responses
200OK
All fields of Journey:
draftobjectgraphobjectentryobject
publishedobject | nullgraphobjectentryobject
- 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
{"exit_all": true} also exits all participants. Only active journeys.Parameters
journeypathintegerrequiredIdempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request body
exit_allboolean
Request body example
{
"exit_all": true
}Responses
200OK
idintegernamestringdescriptionstring | nullstatusstringvalues:
"draft", "active", "paused", "archived"versioninteger | nullnext_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.values:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Resume a paused journey
post/journeys/{journey}/resume
Parameters
journeypathintegerrequiredIdempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Responses
200OK
idintegernamestringdescriptionstring | nullstatusstringvalues:
"draft", "active", "paused", "archived"versioninteger | nullnext_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.values:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Archive: all participants exit
post/journeys/{journey}/archive
Parameters
journeypathintegerrequiredIdempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Responses
200OK
idintegernamestringdescriptionstring | nullstatusstringvalues:
"draft", "active", "paused", "archived"versioninteger | nullnext_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.values:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Submit a journey for approval
post/journeys/{journey}/approval/request
comment.Parameters
journeypathintegerrequired
Request body
commentstringlength:
≤ 1000
Request body example
{
"comment": "string"
}Responses
Approve a journey
post/journeys/{journey}/approval/approve
Parameters
journeypathintegerrequired
Request body
commentstringlength:
≤ 1000
Request body example
{
"comment": "string"
}Responses
Return a journey for changes
post/journeys/{journey}/approval/return
comment is required.Parameters
journeypathintegerrequired
Request bodyrequired
commentstringrequiredlength:
≤ 1000
Request body example
{
"comment": "string"
}Responses
Journey participations, newest first
get/journeys/{journey}/enrollments
Parameters
journeypathintegerrequiredlimitqueryintegerdefault:
50· range:1–200cursorquerystringstatusquerystringvalues:
"active", "waiting", "completed", "exited", "failed"
Responses
200OK
next_cursorstring | nullrequiredPass ascursorto 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
Parameters
journeypathintegerrequiredperiodqueryintegervalues:
7, 30, 90· default:30
Responses
Enroll a profile into a journey with the API trigger
post/journeys/{journey}/enroll
Parameters
journeypathintegerrequiredIdempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
dataobjectAvailable in templates ascontext.data.idempotency_keystringlength:
≤ 150
Request body example
{
"identity": {
"type": "user_id",
"value": "string"
},
"data": {},
"idempotency_key": "string"
}Responses
200Not enrolled (repeat key, re-entry policy, audience or limit)
enrolledbooleanenrollment_idinteger | nullprofile_idinteger
201Enrolled
enrolledbooleanenrollment_idinteger | nullprofile_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
Parameters
limitqueryintegerdefault:
50· range:1–200cursorquerystringchannelquerystringOnly templates of this channel.
Responses
Create a message template
post/templates
Parameters
Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
namestringrequiredlength:
≤ 120channel_keystringrequiredChannel of the template; cannot be changed later.topicstringdefault:
"marketing"· length:≤ 64· pattern:^[a-z0-9_-]+$transactionalbooleandefault:
falselanguagestringMain language ofcontent; the project default language if omitted.length:
≤ 16· example:"de"contentobjectrequiredFields of the channel message schema, e.g.subject,htmlandtextfor email; string fields are Twig templates.translationsobjectOther language versions; each is validated likecontent. Omit to keep the stored versions, pass{}to delete them.keys:
≤ 50
Request body example
{
"name": "string",
"channel_key": "string",
"topic": "marketing",
"transactional": false,
"language": "de",
"content": {},
"translations": {}
}Responses
201Created
idintegernamestringchannelstringexample:
"email"topicstringSubscription topic the message belongs to.transactionalbooleanlanguagestringMain language ofcontent: recipients whose profile language has no version get it.length:
≤ 16· example:"de"contentobjectFields of the channel message schema, e.g.subject,htmlandtextfor email; string fields are Twig templates.translationsobjectOther language versions: language tag → content. A recipient gets the version for thelanguageprofile trait (exact tag, then the base language, then another variant of it), otherwisecontent.versionintegerGrows when any language version changes.created_atstring (date-time) | nullupdated_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}
Parameters
templatepathintegerrequired
Responses
200OK
idintegernamestringchannelstringexample:
"email"topicstringSubscription topic the message belongs to.transactionalbooleanlanguagestringMain language ofcontent: recipients whose profile language has no version get it.length:
≤ 16· example:"de"contentobjectFields of the channel message schema, e.g.subject,htmlandtextfor email; string fields are Twig templates.translationsobjectOther language versions: language tag → content. A recipient gets the version for thelanguageprofile trait (exact tag, then the base language, then another variant of it), otherwisecontent.versionintegerGrows when any language version changes.created_atstring (date-time) | nullupdated_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}
Parameters
templatepathintegerrequired
Request bodyrequired
namestringlength:
≤ 120topicstringdefault:
"marketing"· length:≤ 64· pattern:^[a-z0-9_-]+$transactionalbooleandefault:
falselanguagestringMain language ofcontent; the project default language if omitted.length:
≤ 16· example:"de"contentobjectFields of the channel message schema, e.g.subject,htmlandtextfor email; string fields are Twig templates.translationsobjectOther language versions; each is validated likecontent. Omit to keep the stored versions, pass{}to delete them.keys:
≤ 50
Request body example
{
"name": "string",
"topic": "marketing",
"transactional": false,
"language": "de",
"content": {},
"translations": {}
}Responses
200OK
idintegernamestringchannelstringexample:
"email"topicstringSubscription topic the message belongs to.transactionalbooleanlanguagestringMain language ofcontent: recipients whose profile language has no version get it.length:
≤ 16· example:"de"contentobjectFields of the channel message schema, e.g.subject,htmlandtextfor email; string fields are Twig templates.translationsobjectOther language versions: language tag → content. A recipient gets the version for thelanguageprofile trait (exact tag, then the base language, then another variant of it), otherwisecontent.versionintegerGrows when any language version changes.created_atstring (date-time) | nullupdated_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}
Parameters
templatepathintegerrequired
Responses
Campaigns
List campaigns
get/campaigns
Parameters
limitqueryintegerdefault:
50· range:1–200cursorquerystring
Responses
Create a campaign draft
post/campaigns
Parameters
Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
namestringrequiredlength:
≤ 120descriptionstring | nullintegration_idinteger | nullChannel integration; the template of every variant must belong to its channel.items:
1–5rate_per_minuteinteger | nullrange:
10–100000goalCampaignGoal
Request body example
{
"name": "string",
"description": "string",
"integration_id": 0,
"audience": {
"segment_ids": [
0
],
"exclude_segment_ids": [
0
],
"ignore_control_group": true
},
"variants": [
{
"key": "string",
"template_id": 0,
"percent": 1
}
],
"ab": {
"mode": "test",
"test_percent": 5,
"metric": "opened",
"wait": {
"amount": 1,
"unit": "hour"
}
},
"schedule": {
"type": "now",
"at": "2026-11-01T10:00",
"repeat": "daily",
"time": "10:00",
"weekdays": [
1
],
"day_of_month": 1,
"start_date": "2026-01-01",
"end_date": "2026-01-01",
"local_time": true,
"best_time": true
},
"rate_per_minute": 10,
"goal": {
"event": "string",
"within": {
"amount": 1,
"unit": "hour"
}
}
}Responses
201Created
idintegernamestringdescriptionstring | nullstatusstringvalues:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.values:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Get a campaign
get/campaigns/{campaign}
Parameters
campaignpathintegerrequired
Responses
200OK
idintegernamestringdescriptionstring | nullstatusstringvalues:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.values:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Update a campaign (partial)
patch/campaigns/{campaign}
Parameters
campaignpathintegerrequired
Request bodyrequired
namestringlength:
≤ 120descriptionstring | nullintegration_idinteger | nullChannel integration; the template of every variant must belong to its channel.audienceCampaignAudiencevariantsCampaignVariant[]items:
1–5scheduleCampaignSchedulerate_per_minuteinteger | nullrange:
10–100000goalCampaignGoal
Request body example
{
"name": "string",
"description": "string",
"integration_id": 0,
"audience": {
"segment_ids": [
0
],
"exclude_segment_ids": [
0
],
"ignore_control_group": true
},
"variants": [
{
"key": "string",
"template_id": 0,
"percent": 1
}
],
"ab": {
"mode": "test",
"test_percent": 5,
"metric": "opened",
"wait": {
"amount": 1,
"unit": "hour"
}
},
"schedule": {
"type": "now",
"at": "2026-11-01T10:00",
"repeat": "daily",
"time": "10:00",
"weekdays": [
1
],
"day_of_month": 1,
"start_date": "2026-01-01",
"end_date": "2026-01-01",
"local_time": true,
"best_time": true
},
"rate_per_minute": 10,
"goal": {
"event": "string",
"within": {
"amount": 1,
"unit": "hour"
}
}
}Responses
200OK
idintegernamestringdescriptionstring | nullstatusstringvalues:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.values:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Delete a campaign
delete/campaigns/{campaign}
Parameters
campaignpathintegerrequired
Responses
- 204Deleted
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Campaign report: last runs with per-variant stats
get/campaigns/{campaign}/report
Parameters
campaignpathintegerrequired
Responses
Launch readiness of the campaign
get/campaigns/{campaign}/readiness
Parameters
campaignpathintegerrequired
Responses
200OK
readybooleanrequiredNo errors: the launch will pass.clearbooleanrequiredNo errors and no warnings.checksobject[]requiredkeystringrequiredconfig, archived, quota, sending_domain, integration, untranslated, template_error, unsubscribe, deliverability, segment_pending, segment_empty, segment_broad, goal_missing, goal_unseen, goal_windowlevelstringrequiredvalues:
"error", "warning", "info"messagestringrequiredText in the language of the requestpathstringField 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
now starts within a minute.Parameters
campaignpathintegerrequiredIdempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Responses
200OK
idintegernamestringdescriptionstring | nullstatusstringvalues:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.values:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Pause a campaign
post/campaigns/{campaign}/pause
Parameters
campaignpathintegerrequiredIdempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Responses
200OK
idintegernamestringdescriptionstring | nullstatusstringvalues:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.values:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Resume a paused campaign
post/campaigns/{campaign}/resume
Parameters
campaignpathintegerrequiredIdempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Responses
200OK
idintegernamestringdescriptionstring | nullstatusstringvalues:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.values:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Cancel a campaign
post/campaigns/{campaign}/cancel
Parameters
campaignpathintegerrequiredIdempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Responses
200OK
idintegernamestringdescriptionstring | nullstatusstringvalues:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.values:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Submit a campaign for approval
post/campaigns/{campaign}/approval/request
comment.Parameters
campaignpathintegerrequired
Request body
commentstringlength:
≤ 1000
Request body example
{
"comment": "string"
}Responses
Approve a campaign
post/campaigns/{campaign}/approval/approve
Parameters
campaignpathintegerrequired
Request body
commentstringlength:
≤ 1000
Request body example
{
"comment": "string"
}Responses
Return a campaign for changes
post/campaigns/{campaign}/approval/return
comment is required.Parameters
campaignpathintegerrequired
Request bodyrequired
commentstringrequiredlength:
≤ 1000
Request body example
{
"comment": "string"
}Responses
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.
Parameters
languagequerystringlength:
≤ 35
Responses
200Settings; only enabled: false when the chat is off
enabledbooleanonlinebooleancolorstringpositionstringvalues:
"right", "left"launcherbooleanСтандартная кнопка чата; false — чат открывает своя кнопка сайта (cdp.openChat() или data-cdp-chat).prechatbooleanname_fieldstringИмя в анкете: не спрашивать, необязательно, обязательно (обязательное проверяется у первого сообщения нового диалога).values:
"hidden", "optional", "required"email_fieldstringEmail в анкете: не спрашивать, необязательно, обязательно.values:
"hidden", "optional", "required"offline_emailbooleanТребовать email, когда чат не на связи (проверяет виджет).previewbooleanOperators see what the visitor is typing: send text with POST /chat/typing (stage 97)textsobjecttitlestringgreetingstringofflinestring
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.idintegernamestringonlineboolean
filesobjectDocuments the visitor may attach (stage 97)extensionsstring[]max_mbinteger
fieldsobject[]Pre-chat fields (stage 97) with the label in the visitor languagekeystringtypestringvalues:
"text", "phone", "select"requiredbooleanoptionsstring[]labelstring
surveyobject | nullPost-chat survey (stage 97): questions and texts in the visitor languagekeystringquestionsobject[]textsobject
Messages of the visitor conversation
get/chat/messages
/conversations.Parameters
conversationquerystring (uuid)requiredtokenquerystringrequiredlength:
≤ 64afterqueryintegerrange:
≥ 0readquerybooleanMark operator replies as read by the visitordefault:
true
Responses
200Messages visible to the visitor
conversationChatVisitorConversationmessagesChatVisitorMessage[]
- 403The visitor of this conversation is blocked (code: blocked)
- 404Unknown conversation or wrong token
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.
Request bodyrequired
anonymousIdstringrequiredlength:
≤ 255userIdstringlength:
≤ 255userHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.length:
≤ 128conversationstring (uuid)Conversation id from POST /chat/messagestokenstringVisitor token of the conversation from POST /chat/messageslength:
≤ 64bodystringMessage text. Required unless the message carries images (multipart/form-data).length:
≤ 4000namestringlength:
≤ 100emailstring (email)length:
≤ 255pagestringPage URL (http/https)length:
≤ 2000languagestringlength:
≤ 35customer_tokenstringToken of the customer signed in to the store website, issued by the store (store MCP contract, docs/api/store-mcp.md#5). The store verifies it; the platform stores it encrypted.length:
≤ 2000departmentintegerDepartment 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.invitationintegerAutomatic invitation the visitor replies to (stage 97): its text becomes the first operator message of the new conversationfieldsobjectPre-chat fields set in the chat settings (stage 97): field key → value; unknown keys and select values outside the options are dropped
Request body example
{
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"conversation": "00000000-0000-0000-0000-000000000000",
"token": "string",
"body": "string",
"name": "string",
"email": "string",
"page": "string",
"language": "string",
"customer_token": "string",
"department": 0,
"invitation": 0,
"fields": {}
}Responses
201Message stored
conversationChatVisitorConversationmessageChatVisitorMessage
- 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
/conversations. Shares the presence rate limit, separate from event ingestion (ADR-253).Request bodyrequired
conversationstring (uuid)requiredConversation id from POST /chat/messagestokenstringrequiredVisitor token of the conversation from POST /chat/messageslength:
≤ 64textstring | nullText the visitor is still typing (stage 97), sent when the chat config has preview: true. Operators see the first 500 characters; it is not stored.length:
≤ 4000
Request body example
{
"conversation": "00000000-0000-0000-0000-000000000000",
"token": "string",
"text": "string"
}Responses
- 200Shown to operators of the open conversation
- 403The visitor of this conversation is blocked (code: blocked)
- 404Unknown conversation or wrong token
The visitor is on the site
post/chat/presence
Request bodyrequired
anonymousIdstringrequiredlength:
≤ 255pagestringCurrent page URL (http or https). Only the path and utm_* parameters are kept: the fragment and other parameters are droppedlength:
≤ 2000titlestringlength:
≤ 300referrerstringSite the visit came from; only its scheme and host are keptlength:
≤ 2000sourcestringutm_source of the first page or the referring hostlength:
≤ 100started_atintegerStart of the visit, Unix time in millisecondspagesintegerPages viewed in the visitrange:
≥ 1languagestringlength:
≤ 35conversationstring (uuid)Conversation the widget already knowsinvitationsbooleanReturn the automatic invitations for this visitor
Request body example
{
"anonymousId": "string",
"page": "string",
"title": "string",
"referrer": "string",
"source": "string",
"started_at": 0,
"pages": 1,
"language": "string",
"conversation": "00000000-0000-0000-0000-000000000000",
"invitations": true
}Responses
200The visitor is shown to operators as online for 90 seconds
nextintegerSeconds 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)idintegertextstringsenderstring | nullrulesobject
conversationChatVisitorConversationConversation an operator started with this browser; contains the visitor tokenAll fields of ChatVisitorConversation
- 403The visitor is blocked (code: blocked)
- 404The chat is disabled
- 429Too many requests: presence calls of this browser or new browsers from this IP; wait for Retry-After seconds
Answer the post-chat survey
post/chat/survey
Request bodyrequired
conversationstring (uuid)requiredtokenstringrequiredlength:
≤ 64answersobjectrequiredQuestion id → answer (scale number, option or list of options, text)languagestringlength:
≤ 35
Request body example
{
"conversation": "00000000-0000-0000-0000-000000000000",
"token": "string",
"answers": {},
"language": "string"
}Responses
- 200Recorded; a repeated answer updates the same survey response
- 403The visitor of this conversation is blocked (code: blocked)
- 404Unknown conversation, wrong token or no active post-chat survey
- 422The answers do not fit the questions
- 429More than 5 calls per hour for this conversation
Rate the conversation
post/chat/rating
/conversations.Request bodyrequired
conversationstring (uuid)requiredConversation id from POST /chat/messagestokenstringrequiredVisitor token of the conversation from POST /chat/messageslength:
≤ 64ratingintegerrequiredrange:
1–5commentstringlength:
≤ 1000
Request body example
{
"conversation": "00000000-0000-0000-0000-000000000000",
"token": "string",
"rating": 1,
"comment": "string"
}Responses
200Rating stored
conversationChatVisitorConversation
- 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
/conversations.Request bodyrequired
conversationstring (uuid)requiredConversation id from POST /chat/messagestokenstringrequiredVisitor token of the conversation from POST /chat/messageslength:
≤ 64
Request body example
{
"conversation": "00000000-0000-0000-0000-000000000000",
"token": "string"
}Responses
200The bot handed the conversation over to the operators
conversationChatVisitorConversation
- 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.
Request bodyrequired
conversationstring (uuid)requiredConversation id from POST /chat/messagestokenstringrequiredVisitor token of the conversation from POST /chat/messageslength:
≤ 64
Request body example
{
"conversation": "00000000-0000-0000-0000-000000000000",
"token": "string"
}Responses
200Tokens
urlstringchannelstringconnection_tokenstringsubscription_tokenstring
- 403The visitor of this conversation is blocked (code: blocked)
- 404Unknown conversation or wrong token
Search
Product search for the site
get/search
Write key (tracker, shop plugins), ADR-079. Word forms of the project languages, typos and a query typed in the wrong keyboard layout are understood; a query without results is retried with any of its words (relaxed). With anonymousId the first results are reordered by the categories and brands the visitor looked at (personalized). Facets are counted over the whole query, before the category, brand and price filters.
Every request (and every suggestion request) counts towards the monthly search requests of the plan.
Parameters
qquerystringQuery text; empty — the whole catalog.length:
≤ 200categoryquerystringCategory id; products of its subcategories too.brand[]querystring[]items:
≤ 20price_minquerynumberrange:
≥ 0price_maxquerynumberrange:
≥ 0attrqueryobjectFilters by product characteristics of the store industry (ADR-114), e.g.attr[season]=winter&attr[rim_diameter][]=16&attr[rim_diameter][]=17: any of the values of a key, all keys. Keys and values — fromfacets.attributes.keys:
≤ 20sortquerystringvalues:
"relevance", "popular", "price_asc", "price_desc"· default:"relevance"pagequeryintegerdefault:
1· range:1–100per_pagequeryintegerdefault:
24· range:1–48allquerybooleanInclude products that are not available.default:
falseanonymousIdquerystringTracker visitor id for the personal order.image_widthqueryintegerdefault:
480· range:64–1200languagequerystringVisitor language (BCP 47, as in context.locale): product names and links come in the catalog translation for the closest language (ADR-080).length:
≤ 35correctquerybooleanCorrect typos of a query that finds nothing (default true); false searches exactly the typed text.default:
trueignore[]querystring[]What not to recognize in the query text: price, brand or a characteristic key (the visitor removed the chip of a recognized filter).items:
≤ 20
Responses
200Found products
request_idstring (uuid)querystringtotalintegerpageintegerper_pageintegerrelaxedbooleanNothing matched all words: products matching any word.personalizedbooleanitemsProductCard[]All fields of ProductCard:
availableboolean
facetsobjectcategoriesobject[]idstringnamestringcountinteger
brandsobject[]namestringcountinteger
priceobjectminnumber | nullmaxnumber | null
attributesobject[]Characteristics of the store industry with values and product counts; values go toattr[key].keystringnamestringvaluesobject[]valuestringlabelstringcountinteger
redirectstring (uri) | nullRedirect rule of the query (Site → Search): the page to open instead of the results, or null.filtersobjectFilters recognized in the query text and applied: sizes and characteristics of the store industry (“205/55 r16 winter” → tire_width, tire_profile, rim_diameter, season), catalog values of text characteristics (“red dress” → color), price_min / price_max (“under 3000”, “from 1000 to 2000” in the 10 interface languages) and brand (a catalog brand in the text). Empty when nothing was recognized or nothing matched them (then the text is searched as typed).correctedstring | nullThe query with corrected typos when the typed one found nothing (or only loosely) and the corrected one found products: the items are its results.suggestionstring | null“Did you mean”: the corrected query when nothing was found or only some of the words matched (and nothing was found by meaning); null otherwise.learnedbooleanThe order of the first results takes into account which products visitors clicked and bought for this query (learned daily).semanticbooleanThe results include products found by meaning (vector search): for a descriptive query, or when the words of the query found nothing or only some of them matched.
- 401Missing, invalid or revoked key · Error
402Product search is not in the plan (feature_unavailable) or the monthly search requests are used up beyond the 10% margin (quota_exceeded): fall back to the website's own search.
messagestringcodestringvalues:
"feature_unavailable", "quota_exceeded"
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
AI search
post/search/ai
AI search (ADR-195): the shopper's query in plain words is parsed by AI into catalog filters — categories, brands, attributes, price, exclusions, sorting — and the results come with the chips of what AI understood and follow-up refinements. Used only when the AI search mode of the project wants it for the query (off, auto for descriptive queries, toggle, always); otherwise {ai: null} and the usual results stay. A parse from the cache comes at once; otherwise 202 with id — get the results with GET /search/ai/result. AI filters that find nothing are relaxed step by step. Charged to the project balance by tokens; limited per visitor (10 model parses a minute, 100 a day). Counts as a search request.
Used by the search widget of the tracker; not part of the SDKs.
Request bodyrequired
qstringrequiredlength:
≤ 200previousobjectai.stateof the previous answer: the query refines it ("cheaper", "only Michelin")stateobjectai.stateto search by without the model (a removed chip of what AI understood, the next page); checked against the catalog like a model answeraskedbooleanThe shopper turned on "Ask AI" (toggle mode)sortstringSorting chosen by the shopper; relevance — the sorting AI understoodvalues:
"relevance", "popular", "price_asc", "price_desc"anonymousIdstringlength:
≤ 255languagestringlength:
≤ 35pageintegerrange:
1–100per_pageintegerrange:
≥ 1image_widthintegerrange:
64–1200allboolean
Request body example
{
"q": "string",
"previous": {},
"state": {},
"asked": true,
"sort": "relevance",
"anonymousId": "string",
"language": "string",
"page": 1,
"per_page": 1,
"image_width": 64,
"all": true
}Responses
200Results by the AI parse, or `{ai: null}`
request_idstring (uuid)querystringtotalintegerpageintegerper_pageintegerrelaxedbooleanNothing matched all words: products matching any word.personalizedbooleanitemsProductCard[]All fields of ProductCard:
availableboolean
facetsobjectcategoriesobject[]idstringnamestringcountinteger
brandsobject[]namestringcountinteger
priceobjectminnumber | nullmaxnumber | null
attributesobject[]Characteristics of the store industry with values and product counts; values go toattr[key].keystringnamestringvaluesobject[]valuestringlabelstringcountinteger
redirectstring (uri) | nullRedirect rule of the query (Site → Search): the page to open instead of the results, or null.filtersobjectFilters recognized in the query text and applied: sizes and characteristics of the store industry (“205/55 r16 winter” → tire_width, tire_profile, rim_diameter, season), catalog values of text characteristics (“red dress” → color), price_min / price_max (“under 3000”, “from 1000 to 2000” in the 10 interface languages) and brand (a catalog brand in the text). Empty when nothing was recognized or nothing matched them (then the text is searched as typed).correctedstring | nullThe query with corrected typos when the typed one found nothing (or only loosely) and the corrected one found products: the items are its results.suggestionstring | null“Did you mean”: the corrected query when nothing was found or only some of the words matched (and nothing was found by meaning); null otherwise.learnedbooleanThe order of the first results takes into account which products visitors clicked and bought for this query (learned daily).semanticbooleanThe results include products found by meaning (vector search): for a descriptive query, or when the words of the query found nothing or only some of them matched.aiobjectWhat AI understood (null — usual results stay)understoodobject[]typestringvalues:
"category", "brand", "attribute", "exclude", "price"keystringlabelstring
refinementsstring[]Short follow-up queries for chipsrelaxedinteger0 — all AI filters applied; 1 — without attributes and exclusions; 2 — text and price; 3 — the original textcachedbooleanstateobjectParsed state; send it back aspreviouswith a follow-up query
reasonstringWhy AI was not used: plan, balance, spend_limit, disabled, not_configured, too_many, failed, expired
202The model is parsing the query
pendingbooleanidstring
402Search quota exceeded
messagestringreasonstring
Result of an AI search parsed in the background
get/search/ai/result
Results of POST /search/ai that answered 202: send id and the same q and result parameters. 202 while the model is parsing; then the results by the parse, or {ai: null, reason} if AI was not available or did not answer. The id is kept for 5 minutes.
Used by the search widget of the tracker; not part of the SDKs.
Parameters
idquerystringrequiredlength:
40–40qquerystringrequiredlength:
≤ 200languagequerystringlength:
≤ 35anonymousIdquerystringlength:
≤ 255per_pagequeryintegerimage_widthqueryinteger
Responses
200Results by the AI parse, or `{ai: null}`
request_idstring (uuid)querystringtotalintegerpageintegerper_pageintegerrelaxedbooleanNothing matched all words: products matching any word.personalizedbooleanitemsProductCard[]All fields of ProductCard:
availableboolean
facetsobjectcategoriesobject[]idstringnamestringcountinteger
brandsobject[]namestringcountinteger
priceobjectminnumber | nullmaxnumber | null
attributesobject[]Characteristics of the store industry with values and product counts; values go toattr[key].keystringnamestringvaluesobject[]valuestringlabelstringcountinteger
redirectstring (uri) | nullRedirect rule of the query (Site → Search): the page to open instead of the results, or null.filtersobjectFilters recognized in the query text and applied: sizes and characteristics of the store industry (“205/55 r16 winter” → tire_width, tire_profile, rim_diameter, season), catalog values of text characteristics (“red dress” → color), price_min / price_max (“under 3000”, “from 1000 to 2000” in the 10 interface languages) and brand (a catalog brand in the text). Empty when nothing was recognized or nothing matched them (then the text is searched as typed).correctedstring | nullThe query with corrected typos when the typed one found nothing (or only loosely) and the corrected one found products: the items are its results.suggestionstring | null“Did you mean”: the corrected query when nothing was found or only some of the words matched (and nothing was found by meaning); null otherwise.learnedbooleanThe order of the first results takes into account which products visitors clicked and bought for this query (learned daily).semanticbooleanThe results include products found by meaning (vector search): for a descriptive query, or when the words of the query found nothing or only some of them matched.aiobjectWhat AI understood (null — usual results stay)understoodobject[]typestringvalues:
"category", "brand", "attribute", "exclude", "price"keystringlabelstring
refinementsstring[]Short follow-up queries for chipsrelaxedinteger0 — all AI filters applied; 1 — without attributes and exclusions; 2 — text and price; 3 — the original textcachedbooleanstateobjectParsed state; send it back aspreviouswith a follow-up query
reasonstringWhy AI was not used: plan, balance, spend_limit, disabled, not_configured, too_many, failed, expired
202The model is still parsing
pendingboolean
Short AI answer written so far
get/search/ai/answer
Text of the answer started with POST /search/ai/answer so far: done: false — still being written. The id is kept for 5 minutes.
Used by the search widget of the tracker; not part of the SDKs.
Parameters
idquerystringrequiredlength:
40–40
Responses
200Text so far
answerstringText so far; null — no answer (off, AI not available, too many requests)donebooleanreasonstring
Short AI answer above search results
post/search/ai/answer
One or two sentences about the products found for the query (ADR-195): what fits best, the price range or the key difference — only from the product cards; a sentence with a number the cards do not have is dropped. Off when the AI search mode is off or the project turned the answer off ({answer: null}). A cached answer comes at once; otherwise 202 with id — the text is written in the background and read with GET /search/ai/answer as it grows. Charged to the project balance by tokens; limited per visitor.
Used by the search widget of the tracker; not part of the SDKs.
Request bodyrequired
qstringrequiredlength:
≤ 200productsstring[]requiredIds of the products found, in the order of the resultsitems:
≤ 6languagestringlength:
≤ 35anonymousIdstringlength:
≤ 255
Request body example
{
"q": "string",
"products": [
"string"
],
"language": "string",
"anonymousId": "string"
}Responses
200The answer or `{answer: null}`
answerstringText so far; null — no answer (off, AI not available, too many requests)donebooleanreasonstring
202The model is writing the answer
pendingbooleanidstring
Search suggestions while typing
get/search/suggest
Write key, ADR-079. Products by the beginning of words, categories by name, popular queries of the website (search events of the last 30 days). An empty query returns only the popular queries.
widget=1 is used by the search layer of the tracker: the answer also has brands and pages (website pages of the knowledge base), and an empty q returns trending queries and products for the visitor (anonymousId; personal recommendations, popular products without history; without the recommendations feature of the plan or computed recommendations — popular catalog products in stock).
Parameters
qquerystringlength:
≤ 100limitqueryintegerProducts in the suggestion.default:
6· range:1–10image_widthqueryintegerdefault:
480· range:64–1200languagequerystringVisitor language (BCP 47, as in context.locale): product names and links come in the catalog translation for the closest language (ADR-080).length:
≤ 35widgetquerybooleanAnswer for the search layer of the tracker: brands, website pages, and for an empty query trending queries and products for the visitor.default:
falseanonymousIdquerystringVisitor of the tracker: products for an empty query with widget=1.length:
≤ 255
Responses
200Suggestions
productsProductCard[]All fields of ProductCard:
availableboolean
categoriesobject[]idstringnamestring
queriesstring[]redirectstring (uri) | nullRedirect rule of the query (Site → Search): the page to open instead of the results, or null.brandsobject[]With widget=1: brands of products in stock starting with the query.namestring
pagesobject[]With widget=1: website pages of the knowledge base matching the query (3 characters or more).titlestringurlstring (uri)
correctedstring | nullThe corrected query when products were found only for it.
- 401Missing, invalid or revoked key · Error
402Product search is not in the plan (feature_unavailable) or the monthly search requests are used up beyond the 10% margin (quota_exceeded): fall back to the website's own search.
messagestringcodestringvalues:
"feature_unavailable", "quota_exceeded"
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Website search layer settings
get/search/widget
input[data-cdp-search], the results, category and add-to-cart addresses ({query}, {id}), the blocks to show, the look and texts in the visitor language, and the empty field (blank): the store's own queries and banner in the visitor language. A store whose search page shows <div data-cdp-search-results data-cart-url="…"> instead of its own results checks enabled first.Parameters
languagequerystringlength:
≤ 35
Responses
200Settings; enabled: false when the search layer is off — then also ai and the texts of the AI block when AI search is on (the AI block above the results of the store's own search)
enabledbooleanselectorstring | nullresults_urlstring | nullResults page with {query}; null — the form of the search field.category_urlstring | nullCategory page with {id}; null — categories are not shown.cart_urlstring | nullAdd-to-cart address with {id} — the catalog product id; the “Add to cart” button of the results widget sends POST to it (quantity, form_key from the cookie if present) and expects JSON: {"ok": true} or {"redirect": "…"} for a product that needs options. null — no button unless the page container sets data-cart-url.sectionsobjecthistorybooleantrendingbooleanproductsbooleancategoriesbooleanbrandsbooleanpagesboolean
textsobjectaccentstringAccent color, #rrggbb.radiusintegercolumnsintegerColumns of the results grid; 0 — by the width.ratiostringvalues:
"square", "portrait"voicebooleanaiobject | nullAI search mode of the project (null — off): when the results widget asks POST /search/ai, shows "Ask AI" and the short answermodestringvalues:
"auto", "toggle", "always"answerboolean
blankobjectEmpty search field in the visitor language (the project language closest to it, otherwise the default one): own queries shown first among trending ones (even with the trending block off) and a banner above the products.queriesstring[]items:
≤ 8bannerobject | nullimagestringhttps image address.urlstring | nullWebsite address or path; null — the banner is not a link.altstring
Analytics
Run an event report
post/analytics/reports
definition and the result — the same as the analytics pages.Request bodyrequired
seriesobject[]requireditems:
1–5eventstring | nullmetricstringvalues:
"count", "profiles", "per_profile", "sum", "avg"propertystring | nullfiltersPropertyFilter[]
profilesProfileRulesbreakdownBreakdownintervalAnalyticsIntervalperiodAnalyticsPeriodcompareboolean
Request body example
{
"series": [
{
"event": "string",
"metric": "count",
"property": "string",
"filters": [
{
"key": "string",
"operator": "string",
"value": null
}
]
}
],
"profiles": {},
"breakdown": {
"source": "property",
"key": "string",
"limit": 10
},
"interval": "day",
"period": {
"last": 7
},
"compare": true
}Responses
200OK
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
bucketsstring (date)[]requiredseriesobject[]requiredPer 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
definition and the result — the same as the analytics pages.Request bodyrequired
stepsobject[]requireditems:
2–10eventstringrequiredfiltersPropertyFilter[]
windowobjectConversion window from the first step, up to 90 daysamountintegerrange:
≥ 1unitstringvalues:
"minute", "hour", "day"
orderstringvalues:
"sequential", "strict"profilesProfileRulesbreakdownBreakdownperiodAnalyticsPeriod
Request body example
{
"steps": [
{
"event": "string",
"filters": [
{
"key": "string",
"operator": "string",
"value": null
}
]
}
],
"window": {
"amount": 1,
"unit": "minute"
},
"order": "sequential",
"profiles": {},
"breakdown": {
"source": "property",
"key": "string",
"limit": 10
},
"period": {
"last": 7
}
}Responses
200OK
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
stepsobject[]requiredPer step: event, reached, from_start, from_previous, median_seconds, avg_secondsbreakdownobject[]requiredPer breakdown value: value, steps (reached per step)time_samplenumberShare 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
definition and the result — the same as the analytics pages.Request bodyrequired
startobjectrequiredeventstring | nullfiltersPropertyFilter[]
returnobjecteventstring | nullfiltersPropertyFilter[]
cohortstringvalues:
"first", "period"intervalAnalyticsIntervalperiodsintegerUp to 30 days, 12 weeks or 12 monthsrange:
1–30returnsstringvalues:
"exact", "rolling"profilesProfileRulesperiodAnalyticsPeriod
Request body example
{
"start": {
"event": "string",
"filters": [
{
"key": "string",
"operator": "string",
"value": null
}
]
},
"return": {
"event": "string",
"filters": [
{
"key": "string",
"operator": "string",
"value": null
}
]
},
"cohort": "first",
"interval": "day",
"periods": 1,
"returns": "exact",
"profiles": {},
"period": {
"last": 7
}
}Responses
200OK
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
cohortsobject[]requiredPer cohort: date, size, values (returned per period, null — not yet), open (period still running)averageobject[]requiredPer 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
definition and the result — the same as the analytics pages.Request bodyrequired
eventstringrequiredfiltersPropertyFilter[]directionstringvalues:
"after", "before"stepsintegerrange:
1–5gap_minutesintegerrange:
1–1440excludestring[]items:
≤ 20profilesProfileRulesperiodAnalyticsPeriod
Request body example
{
"event": "string",
"filters": [
{
"key": "string",
"operator": "string",
"value": null
}
],
"direction": "after",
"steps": 1,
"gap_minutes": 1,
"exclude": [
"string"
],
"profiles": {},
"period": {
"last": 7
}
}Responses
200OK
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
totalintegerrequirednodesobject[]requiredlinksobject[]requiredpathsobject[]requiredMost frequent paths: events, profilestruncatedboolean
- 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
definition and the result — the same as the analytics pages.Request bodyrequired
eventstringPurchase event; by default from the prediction settingsamountstringNumeric order amount propertyproduct_propertystringintervalAnalyticsIntervalltv_intervalstringvalues:
"week", "month"ltv_periodsintegerrange:
1–12profilesProfileRulesperiodAnalyticsPeriod
Request body example
{
"event": "string",
"amount": "string",
"product_property": "string",
"interval": "day",
"ltv_interval": "week",
"ltv_periods": 1,
"profiles": {},
"period": {
"last": 7
}
}Responses
200OK
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
currencystring | nullother_currency_ordersintegersummaryobjectrequiredseriesobjectrequiredltvobjectrequiredproductsobject[]requiredcategoriesobject[]required
- 401Missing, invalid or revoked key · Error
- 402Revenue, traffic, attribution and ROPO reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Run a traffic sources report
post/analytics/traffic
definition and the result — the same as the analytics pages.Request bodyrequired
dimensionstringvalues:
"channel", "source", "source_medium", "campaign", "referrer", "landing"intervalAnalyticsIntervaleventstringamountstringprofilesProfileRulesperiodAnalyticsPeriod
Request body example
{
"dimension": "channel",
"interval": "day",
"event": "string",
"amount": "string",
"profiles": {},
"period": {
"last": 7
}
}Responses
200OK
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
currencystring | nullpurchasesbooleansummaryobjectrequiredrowsobject[]requiredrow_countintegerchartobjectrequired
- 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
definition and the result — the same as the analytics pages.Request bodyrequired
window_daysintegervalues:
1, 3, 7, 14, 30modelstringvalues:
"last", "first", "linear"intervalAnalyticsIntervaleventstringamountstringprofilesProfileRulesperiodAnalyticsPeriod
Request body example
{
"window_days": 1,
"model": "last",
"interval": "day",
"event": "string",
"amount": "string",
"profiles": {},
"period": {
"last": 7
}
}Responses
200OK
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
currencystring | nullsummaryobjectrequiredchannelsobject[]requiredPer channel: channel, clicks, touched_orders, revenue and orders by modelitemsobject[]requiredPer campaign, journey, message channel or widgetchartobject
- 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
/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.Request bodyrequired
window_daysintegerOnline touches no earlier than this many days before the in-store check (default 30)values:
1, 3, 7, 14, 30, 60, 90touchesstring[]Kinds of online touches: website visit (source — traffic channel), product view, message click (default — all)intervalAnalyticsIntervaleventstringPurchase event (default — from the project settings)amountstringNumeric amount property of the purchase eventproduct_propertystringProduct id property in products[] lines (default — from the recommendation settings)profilesProfileRulesperiodAnalyticsPeriod
Request body example
{
"window_days": 1,
"touches": [
"visit"
],
"interval": "day",
"event": "string",
"amount": "string",
"product_property": "string",
"profiles": {},
"period": {
"last": 7
}
}Responses
200OK
definitionobjectrequiredNormalized definitionpendingbooleanOnly in a 202 response: the report of a large project is being calculated in the queue — repeat the request laterperiodobjectfromstring (date)tostring (date)
currencystring | nullwindow_daysintegertouchesstring[]product_viewsbooleanThe project has a product view event: products are matched to viewssummaryobjectoffline_revenue, offline_orders, offline_buyers, ropo_revenue, ropo_orders, ropo_buyers, ropo_share, ropo_orders_share, online_revenue, online_orders, median_dayscomparisonobjectropo and offline_only customers: buyers, orders, revenue, aov, orders_per_buyer, revenue_per_buyerreverseobjectOnline orders after an in-store purchase within the window (showrooming): online_orders, online_revenue, orders, revenue, buyers, sharesourcesobject[]Per touch source: kind (visit or message), channel, orders, revenue, buyers, share. A check counts towards every source in its windowstoresobject[]Per store: id, name, city, orders, revenue, buyers, ropo_orders, ropo_revenue, ropo_share, aov, ropo_aov, other_aov, showroom_orders, showroom_revenueproductsobject[]Products viewed online and bought in store (top 20): id, name, orders, viewed_orders, viewed_sharedaysobject[]Checks with a touch by days from the first touch: from, to, orders, revenuechartobjectbuckets, ropo_revenue, other_offline_revenue, showroom_revenue
202The report is being calculated in the queue: repeat the request after Retry-After seconds
definitionobjectrequiredNormalized definitionpendingbooleanOnly in a 202 response: the report of a large project is being calculated in the queue — repeat the request laterperiodobjectfromstring (date)tostring (date)
currencystring | nullwindow_daysintegertouchesstring[]product_viewsbooleanThe project has a product view event: products are matched to viewssummaryobjectoffline_revenue, offline_orders, offline_buyers, ropo_revenue, ropo_orders, ropo_buyers, ropo_share, ropo_orders_share, online_revenue, online_orders, median_dayscomparisonobjectropo and offline_only customers: buyers, orders, revenue, aov, orders_per_buyer, revenue_per_buyerreverseobjectOnline orders after an in-store purchase within the window (showrooming): online_orders, online_revenue, orders, revenue, buyers, sharesourcesobject[]Per touch source: kind (visit or message), channel, orders, revenue, buyers, share. A check counts towards every source in its windowstoresobject[]Per store: id, name, city, orders, revenue, buyers, ropo_orders, ropo_revenue, ropo_share, aov, ropo_aov, other_aov, showroom_orders, showroom_revenueproductsobject[]Products viewed online and bought in store (top 20): id, name, orders, viewed_orders, viewed_sharedaysobject[]Checks with a touch by days from the first touch: from, to, orders, revenuechartobjectbuckets, 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
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.Request bodyrequired
intervalAnalyticsIntervaleventstringPurchase event; defaults to the purchase event of the project settings. Without it the report has no purchasesamountstringNumeric property with the order amountperiodAnalyticsPeriod
Request body example
{
"interval": "day",
"event": "string",
"amount": "string",
"period": {
"last": 7
}
}Responses
200OK
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
currencystring | nullpurchasesbooleanattribution_daysintegersummaryobjectrequiredcurrentandpreviousperiod: requests, searches, product_clicks, carts, cart_clicks, assistant_orders, visits, visitors, orders, revenueassistantsobject[]requiredchartobjectrequiredbucketsand per assistantrequestsandvisitsby bucketqueriesobject[]requiredquerystringcountintegeremptyintegerSearches without results
productsobject[]requiredidstringnamestring | nullrequestsintegerclicksinteger
- 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
Parameters
limitqueryintegerdefault:
50· range:1–200cursorquerystring
Responses
Save a report
post/analytics/saved-reports
definition.* paths.Parameters
Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
namestringrequiredlength:
≤ 120definitionobjectrequiredDefinition of the report type — see the run operationsviewobject
Request body example
{
"name": "string",
"type": "report",
"definition": {},
"view": {}
}Responses
201Created
All fields of SavedReport:
definitionobjectrequiredviewobjectrequiredPage 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}
Parameters
reportpathintegerrequired
Responses
200OK
All fields of SavedReport:
definitionobjectrequiredviewobjectrequiredPage 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}
Parameters
reportpathintegerrequired
Request bodyrequired
namestringlength:
≤ 120definitionobjectviewobject
Request body example
{
"name": "string",
"definition": {},
"view": {}
}Responses
200OK
All fields of SavedReport:
definitionobjectrequiredviewobjectrequiredPage 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}
Parameters
reportpathintegerrequired
Responses
Run a saved report
post/analytics/saved-reports/{report}/result
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.Parameters
reportpathintegerrequired
Request bodyrequired
periodAnalyticsPeriod
Request body example
{
"period": {
"last": 7
}
}Responses
200OK
An object with arbitrary keys.
- 202A ROPO report of a large project is being calculated in the queue (`pending: true`): repeat the request after Retry-After seconds
- 401Missing, invalid or revoked key · Error
- 402Revenue, traffic, attribution and ROPO reports are not in the plan of the project (code feature_unavailable, feature revenue_analytics)
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
- 503The queued calculation failed; the next request starts it again
List dashboards
get/analytics/dashboards
Parameters
limitqueryintegerdefault:
50· range:1–200cursorquerystring
Responses
Create a dashboard
post/analytics/dashboards
Parameters
Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
namestringrequiredlength:
≤ 120layoutobject[]items:
≤ 24report_idintegerrequiredsizestringvalues:
"half", "full"
periodAnalyticsPeriodmainbooleantrue makes the dashboard main (the previous main dashboard stops being main). The flag cannot be cleared: make another dashboard main instead.
Request body example
{
"name": "string",
"layout": [
{
"report_id": 0,
"size": "half"
}
],
"period": {
"last": 7
},
"main": true
}Responses
201Created
idintegerrequirednamestringrequiredlayoutobject[]requireditems:
≤ 24report_idintegerrequiredsizestringvalues:
"half", "full"
mainbooleanrequiredThe 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)requiredupdated_atstring (date-time)required
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Get a dashboard
get/analytics/dashboards/{dashboard}
Parameters
dashboardpathintegerrequired
Responses
200OK
idintegerrequirednamestringrequiredlayoutobject[]requireditems:
≤ 24report_idintegerrequiredsizestringvalues:
"half", "full"
mainbooleanrequiredThe 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)requiredupdated_atstring (date-time)required
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 429Rate limit or monthly event quota exceeded · Error
Update a dashboard
patch/analytics/dashboards/{dashboard}
layout replaces the whole layout.Parameters
dashboardpathintegerrequired
Request bodyrequired
namestringlength:
≤ 120layoutobject[]items:
≤ 24report_idintegerrequiredsizestringvalues:
"half", "full"
periodAnalyticsPeriodmainbooleantrue makes the dashboard main (the previous main dashboard stops being main). The flag cannot be cleared: make another dashboard main instead.
Request body example
{
"name": "string",
"layout": [
{
"report_id": 0,
"size": "half"
}
],
"period": {
"last": 7
},
"main": true
}Responses
200OK
idintegerrequirednamestringrequiredlayoutobject[]requireditems:
≤ 24report_idintegerrequiredsizestringvalues:
"half", "full"
mainbooleanrequiredThe 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)requiredupdated_atstring (date-time)required
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Delete a dashboard
delete/analytics/dashboards/{dashboard}
Parameters
dashboardpathintegerrequired
Responses
List periods of the global control group
get/control-group/periods
ended_at: null. The control group is turned on, resized and turned off only in the project settings, not through the API.Parameters
limitqueryintegerdefault:
50· range:1–200cursorquerystring
Responses
200OK
next_cursorstring | nullrequiredPass ascursorto 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
Parameters
periodpathintegerrequired
Responses
200OK
periodControlGroupPerioduntilstring (date-time)End of the calculation: the end of the period or the next full hour for the active onecurrencystring | nulleventstringPurchase event from the revenue settings of the projectgroupsobjectcontrol— profiles of the control group,target— everyone elsecontrolControlGroupSidetargetControlGroupSide
conversionAbStatsrevenue_per_profileobject | nullWelch z-test of revenue per profile, target against control; null with fewer than 30 profiles in a groupcontrolnumberMean revenue per profile of the control grouptreatmentnumberMean revenue per profile of everyone elsedifferencenumbercinumber[]95 % interval of the differenceitems:
2–2liftnumber | nullp_valuenumbersignificantboolean
incrementalobjectEffect of the communications: (target per profile − control per profile) × target profilesrevenuenumberrevenue_cinumber[] | nullitems:
2–2ordersintegerbuyersinteger
other_currency_ordersintegerOrders in another currency, not countedheld_messagesintegerMarketing messages not sent to the control group in the periodseriesobjectCumulative incremental revenue by day (by week for periods longer than 120 days)intervalstringvalues:
"day", "week"bucketsstring (date)[]incremental_revenuenumber[]controlnumber[]Cumulative revenue per profiletargetnumber[]
exemptobjectCampaigns and journeys of the period with «send to the control group too»: the effect is understatedcampaignsobject[]idintegernamestring
journeysobject[]idintegernamestring
- 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
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).Request bodyrequired
amountnumberrequiredCart amount in the project currencyrange:
≥ 0
Request body example
{
"profile": {
"type": "user_id",
"value": "string"
},
"amount": 0
}Responses
200OK
memberbooleanbalanceintegertierstring | nullmax_pointsintegermax_discountnumberearn_pointsintegerpoint_valuenumbercurrencystring | 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}
member: false.Parameters
typepathstringrequiredvalues:
"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"valuepathstringrequiredNormalized like at ingestion (lower-case email, E.164 phone).
Responses
200OK
memberbooleanbalanceintegerAvailable pointspendingintegerPoints waiting for the return periodtierstring | nulltier_spendnumberexpiringintegerPoints expiring within 30 daysexpires_atstring (date-time) | nullenrolled_atstring (date-time) | nullreferral_codestring | nullCode of the member for inviting friends.referral_urlstring | nullReferral link (?ref=on the store page) when referrals are on.referralsobjectFriends who came with the code, of them rewarded, and points for them.invitedintegerrewardedintegerpointsinteger
- 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
earn, cancel, expire, adjust, redeem (a hold or a redemption), refund (points returned). Cursor pages.Parameters
typepathstringrequiredvalues:
"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"valuepathstringrequiredNormalized like at ingestion (lower-case email, E.164 phone).limitqueryintegerdefault:
50· range:1–200cursorquerystring
Responses
Join the program
post/loyalty/members
enrollment: explicit). Returns 200 if the profile is already a member.Parameters
Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
Request body example
{
"profile": {
"type": "user_id",
"value": "string"
}
}Responses
201Created
memberbooleanbalanceintegerAvailable pointspendingintegerPoints waiting for the return periodtierstring | nulltier_spendnumberexpiringintegerPoints expiring within 30 daysexpires_atstring (date-time) | nullenrolled_atstring (date-time) | nullreferral_codestring | nullCode of the member for inviting friends.referral_urlstring | nullReferral link (?ref=on the store page) when referrals are on.referralsobjectFriends who came with the code, of them rewarded, and points for them.invitedintegerrewardedintegerpointsinteger
- 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
code: referrals off, unknown code, own code, existing customer.Parameters
Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
codestringrequiredlength:
≤ 16
Request body example
{
"profile": {
"type": "user_id",
"value": "string"
},
"code": "string"
}Responses
200Counted before
statusstringpending— waiting for the friend's first order.values:
"pending", "rewarded", "expired", "limit", "cancelled"codestringfriend_pointsintegerfriend_promo_codestring | nullrewardedbooleanThe friend has received the reward.expires_atstring (date-time)The first order of the friend rewards the member until this moment.
201Counted
statusstringpending— waiting for the friend's first order.values:
"pending", "rewarded", "expired", "limit", "cancelled"codestringfriend_pointsintegerfriend_promo_codestring | nullrewardedbooleanThe 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
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.Parameters
Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
pointsintegerrequiredrange:
≥ 1cart_idstringrequiredlength:
≤ 255amountnumberrange:
≥ 0
Request body example
{
"profile": {
"type": "user_id",
"value": "string"
},
"points": 1,
"cart_id": "string",
"amount": 0
}Responses
201Created
idstringstatusstringvalues:
"held", "confirmed", "cancelled", "expired"pointsintegerreturnedintegerdiscountnumbercart_idstringorder_idstring | nullheld_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
order_refunded, order_cancelled) return the points proportionally. Repeating with the same order changes nothing; an expired or cancelled hold — 422.Parameters
redemptionpathstringrequiredRedemption id from the hold response.Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
order_idstringrequiredlength:
≤ 255
Request body example
{
"order_id": "string"
}Responses
200OK
idstringstatusstringvalues:
"held", "confirmed", "cancelled", "expired"pointsintegerreturnedintegerdiscountnumbercart_idstringorder_idstring | nullheld_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
Parameters
redemptionpathstringrequiredRedemption id from the hold response.
Responses
200OK
idstringstatusstringvalues:
"held", "confirmed", "cancelled", "expired"pointsintegerreturnedintegerdiscountnumbercart_idstringorder_idstring | nullheld_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
Idempotency-Key to make retries safe.Parameters
Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
pointsintegerrequiredPositive — add, negative — take offreasonstringrequiredlength:
≤ 500
Request body example
{
"profile": {
"type": "user_id",
"value": "string"
},
"points": 0,
"reason": "string"
}Responses
200OK
memberbooleanbalanceintegerAvailable pointspendingintegerPoints waiting for the return periodtierstring | nulltier_spendnumberexpiringintegerPoints expiring within 30 daysexpires_atstring (date-time) | nullenrolled_atstring (date-time) | nullreferral_codestring | nullCode of the member for inviting friends.referral_urlstring | nullReferral link (?ref=on the store page) when referrals are on.referralsobjectFriends who came with the code, of them rewarded, and points for them.invitedintegerrewardedintegerpointsinteger
- 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
Responses
200OK
dataPromoPool[]
- 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}
Parameters
keypathstringrequiredPool key — the name used in templates:{{ promo_code('summer') }}.pattern:
^[a-z0-9_]{1,64}$
Responses
200OK
keystringrequirednamestringrequiredtypestringrequiredshared— one code for everyone;unique— a separate code for every profile.values:
"shared", "unique"statusstringrequiredvalues:
"active", "paused"activebooleanrequiredActive now: not paused and within the promotion period.discountstring | nullDiscount text for messages, e.g. «−10 %». The discount itself is a coupon rule of the store.starts_atstring (date-time) | nullends_atstring (date-time) | nullEnd of the promotion (exclusive).validity_daysinteger | nullA code is valid for this many days after it is issued (not longer than the promotion).per_profileintegerrequiredHow many codes of the pool one profile can receive.statsobjectrequiredtotalintegeravailableintegerissuedintegerusedintegerusesintegerrevenuenumberSum 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
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.Parameters
keypathstringrequiredPool key — the name used in templates:{{ promo_code('summer') }}.pattern:
^[a-z0-9_]{1,64}$sincequerystringCursor from the previous response.limitqueryintegerdefault:
500· range:1–1000
Responses
200OK
dataPromoCode[]nextstring | nullCursor 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
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.Parameters
keypathstringrequiredPool key — the name used in templates:{{ promo_code('summer') }}.pattern:
^[a-z0-9_]{1,64}$Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
countintegerrange:
1–50000codesstring[]items:
≤ 100000
Request body example
{
"count": 1,
"codes": [
"string"
]
}Responses
201Created
addedintegerskippedinteger
- 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
$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).Parameters
keypathstringrequiredPool key — the name used in templates:{{ promo_code('summer') }}.pattern:
^[a-z0-9_]{1,64}$Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
Request body example
{
"profile": {
"type": "user_id",
"value": "string"
}
}Responses
200Already issued
poolstringPool key.codestringrequiredstatusstringrequiredvalues:
"available", "issued", "used", "shared"issued_atstring (date-time) | nullexpires_atstring (date-time) | nullused_atstring (date-time) | null
201Issued
poolstringPool key.codestringrequiredstatusstringrequiredvalues:
"available", "issued", "used", "shared"issued_atstring (date-time) | nullexpires_atstring (date-time) | nullused_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
messagestringreasonstringvalues:
"inactive", "limit", "exhausted"
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Check a code
get/promo/codes/{code}
Parameters
codepathstringrequiredPromo code, case-insensitive.length:
≤ 64
Responses
200OK
All fields of PromoCode:
activebooleanIssued (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
Parameters
typepathstringrequiredvalues:
"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"valuepathstringrequiredNormalized like at ingestion (lower-case email, E.164 phone).
Responses
200OK
dataPromoCode[]All fields of PromoCode:
activeboolean
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
- 429Rate limit or monthly event quota exceeded · Error
Messages
Send one message now
post/messages
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.Parameters
Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
- The recipient. A profile with this identity is created if there is none.
traitsobjectTraits written to the profile before sending, available in the template astraits.*.keys:
≤ 100template_idintegerMessage 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 | nullChannel integration of the template's channel; may be omitted when the channel has exactly one active integration.dataobjectPer-message data, available in the template ascontext.data.*(order number, confirmation code).stepsCascadeStep[]Cascade (plans with thecascadesfeature): channels tried in order — the next one when the profile cannot be reached on the previous, or its message was not sent, not delivered or not read within the step time.items:
2–5
Request body example
{
"identity": {
"type": "user_id",
"value": "string"
},
"traits": {},
"template_id": 0,
"integration_id": 0,
"data": {},
"steps": [
{
"integration_id": 0,
"template_id": 0,
"wait_for": "sent",
"timeout": {
"amount": 1,
"unit": "minute"
}
}
]
}Responses
202Queued: a message, or a cascade when `steps` are given
One of:
- 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
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.Parameters
Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
tostring (email)requiredRecipient address. The profile is found by this email or created.length:
≤ 254subjectstringRequired unless an order template is enabled forkindandorderis given.length:
≤ 998htmlstringReady HTML of the store email. Sent as is: it is not a template, braces are not processed. Required unless an order template is enabled forkindandorderis given.length:
≤ 1000000textstring | nullPlain-text part; built from the HTML when empty.length:
≤ 1000000reply_tostring (email) | nullOverrides the Reply-To of the email integration.from_namestring | nullOverrides the sender name of the email integration; the sender address is always the integration's.length:
≤ 100kindstringrequiredWhat 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. Fororder_placed,order_paid,order_shipped,order_delivered,order_cancelled,order_refundedwithorder, an enabled OneTrace template builds the email instead ofhtml(seeGET /emails/settings).pattern:
^[a-z0-9_]{1,40}$languagestring | nullCustomer language tag: picks the language version of an order template; for history and reports otherwise.length:
≤ 20integration_idinteger | nullEmail integration; may be omitted when the project has exactly one active.traitsobject | nullProfile traits to update before sending (name, phone).attachmentsobject[]Up to 5 files, 5 MB in total.items:
≤ 5namestringrequiredlength:
≤ 200typestringrequiredvalues:
"application/pdf", "image/png", "image/jpeg", "image/gif", "text/plain", "text/csv", "text/calendar"contentstring (byte)requiredFile contents in base64.
orderStoreOrder
Request body example
{
"to": "string",
"subject": "string",
"html": "string",
"text": "string",
"reply_to": "string",
"from_name": "string",
"kind": "string",
"language": "string",
"integration_id": 0,
"traits": {},
"attachments": [
{
"name": "string",
"type": "application/pdf",
"content": "string"
}
],
"order": {
"order_id": "string",
"number": "string",
"url": "https://example.com",
"created_at": "2026-01-01T10:00:00Z",
"currency": "string",
"amount": 0,
"subtotal": 0,
"discount": 0,
"shipping": 0,
"tax": 0,
"refund_amount": 0,
"coupon": "string",
"payment_method": "string",
"shipping_method": "string",
"carrier": "string",
"tracking_number": "string",
"tracking_url": "https://example.com",
"estimated_delivery": "2026-01-01",
"reason": "string",
"note": "string",
"payment_instructions": "string",
"products": [
{
"product_id": "string",
"variant_id": "string",
"sku": "string",
"product_name": "string",
"quantity": 0,
"price": 0,
"total": 0,
"image_url": "https://example.com",
"url": "https://example.com",
"options": "string"
}
],
"shipping_address": {
"name": "string",
"company": "string",
"address1": "string",
"address2": "string",
"city": "string",
"region": "string",
"postcode": "string",
"country": "string",
"phone": "string"
},
"billing_address": {
"name": "string",
"company": "string",
"address1": "string",
"address2": "string",
"city": "string",
"region": "string",
"postcode": "string",
"country": "string",
"phone": "string"
}
}
}Responses
202Queued
All fields of MessageStatus:
kindstring | nulltemplatebooleanThe 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
Responses
200Settings
relaybooleanSend all store emails through OneTrace (store emails section).integration_idinteger | nulltemplatesobjectOrder email kinds built from OneTrace templates: the store does not send its own email for them and passesorderinstead.
- 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}
POST /messages and the messages of its steps.Parameters
cascadepathstring (uuid)requiredCascadeid(UUID) from the send response.
Responses
200OK
idstring (uuid)statusstringreached— a step succeeded;failed— no channel reached the profile.values:
"running", "reached", "failed"stepintegerCurrent step, from 0.reached_channelstring | nullprofile_idintegeroriginstring | nullcreated_atstring (date-time) | nullfinished_atstring (date-time) | nullmessagesMessageStatus[]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}
POST /messages (or any message of the project by its id).Parameters
messagepathstring (uuid)requiredMessageid(UUID) from the send response.
Responses
200OK
idstring (uuid)statusstringqueued→sent→delivered;scheduled— waiting (quiet hours, warm-up);skipped— not sent, seereason;failed/bounced— seereasonanderror.values:
"queued", "scheduled", "sent", "delivered", "failed", "skipped", "bounced"reasonstring | nullWhy 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 | nullchannelstringtemplate_idinteger | nullintegration_idinteger | nullprofile_idintegertransactionalbooleanoriginstring | nullapifor messages sent withmessages.send,storefor store emails (emails.send).created_atstring (date-time) | nullscheduled_forstring (date-time) | nullsent_atstring (date-time) | nulldelivered_atstring (date-time) | nullopened_atstring (date-time) | nullclicked_atstring (date-time) | nullfailed_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
Parameters
statusquerystringopen— waiting for an answer.values:
"open", "waiting", "closed"channelquerystringvalues:
"web", "telegram", "whatsapp", "viber", "max", "vk", "instagram", "messenger", "email"profile_typequerystringIdentity type of the customer; together withprofile_value.values:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push"profile_valuequerystringIdentity value of the customer; together withprofile_type.length:
≤ 255limitqueryintegerdefault:
50· range:1–200cursorquerystring
Responses
200OK
next_cursorstring | nullrequiredPass ascursorto 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}
Parameters
conversationpathstring (uuid)requiredConversationid(UUID).limitqueryintegerHow many latest messages to return.default:
100· range:1–500
Responses
200OK
All fields of Conversation:
- The latest messages, oldest first.
- 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
Answer in a conversation
post/conversations/{conversation}/messages
Parameters
conversationpathstring (uuid)requiredConversationid(UUID).Idempotency-KeyheaderstringRepeat-safe retries: same key and body return the stored response (headerIdempotent-Replayed: true); a different body gives 422; a request still in progress gives 409.length:
≤ 255
Request bodyrequired
bodystringPlain text of the answer. Optional when products are given (stage 97).length:
1–4000buttonsstring[]Quick reply buttons (stage 97): the website widget, Telegram and Viber show buttons, WhatsApp up to three buttons of up to 20 characters, other channels a numbered list; a press arrives as the customer message with the label. Need body.items:
≤ 10productsstring[]Catalog product ids for product cards (stage 97): a card with the image, name, price and link; in messengers — a separate message.items:
≤ 4
Request body example
{
"body": "string",
"buttons": [
"string"
],
"products": [
"string"
]
}Responses
201Created
idintegerrequiredauthorstringrequiredvisitor— the customer;operator— an answer from the inbox or the API;system— assignment, closing and reopening (seeaction).values:
"visitor", "operator", "system"viastring | nullWhere an answer or action came from: the operator inbox or the API.values:
"inbox", "api", nullapi_keystring | nullName of the API key that answered or closed the conversation.bodystringrequiredMessage text; empty for system messages except notesactionstring | nullAction of a system message; note — an internal note for operators (body is its text), never shown to the customervalues:
"assigned", "unassigned", "routed", "transferred", "closed", "reopened", "bot_handoff", "store_action", "note", nullproduct_idstring | nullProduct the customer asked about with this message, id in the catalogstatusstring | nullDelivery status of an answer sent to a messenger: queued, sent, delivered, failed, skipped, bounced.created_atstring (date-time)requiredimagesobject[]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)statusstringvalues:
"ready", "pending", "failed", "expired"urlstring (uri) | nullwidthinteger | nullheightinteger | 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 firstpending(downloading from the messenger) orchecking(stored, checked for active content and by the antivirus in the background) without url, thenreadyorfailed; themessage.createdwebhook carries the first state.idstringstatusstringvalues:
"pending", "checking", "ready", "failed", "expired"namestringmimestring | nullsizeinteger | nullurlstring | null
buttonsstring[]Quick reply buttons of the reply (stage 97)productsobject[]Product cards of the reply (stage 97)idstringnamestringurlstring | nullpricenumber | nullcurrencystring | 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
Parameters
conversationpathstring (uuid)requiredConversationid(UUID).
Responses
200OK
idstring (uuid)requiredprofile_idintegerrequiredchannelstringrequiredweb— the website chat; messengers need thechat_messengersplan feature.values:
"web", "telegram", "whatsapp", "viber", "max", "vk", "instagram", "messenger", "email"statusstringrequiredopen— the customer wrote last and waits for an answer;waiting— answered, waiting for the customer;closed.values:
"open", "waiting", "closed"assignedbooleanrequiredAn operator is responsible for the conversation.unread_countintegerrequiredCustomer messages operators have not read yet.languagestring | nullproduct_idstring | nullLast product the customer asked about from the site (product question widget or a product page), id in the catalogtagsstring[]Tag names from the project tag dictionary, set by operators (stage 97)ratinginteger | nullCustomer rating after the conversation.range:
1–5rating_commentstring | nulllast_message_atstring (date-time) | nulllast_message_authorstring | nullvalues:
"visitor", "operator", "system", nullfirst_reply_atstring (date-time) | nullcreated_atstring (date-time)requiredclosed_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
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.Request bodyrequired
urlstring (uri)requiredHTTPS address of the store MCP serverlength:
≤ 2048keystringrequiredBearer key the platform sends to the storelength:
32–500namestringlength:
≤ 120platformstringvalues:
"woocommerce", "magento", "bitrix", "sdk", "custom"
Request body example
{
"url": "https://example.com",
"key": "string",
"name": "string",
"platform": "woocommerce"
}Responses
200Updated
idstring (uuid)urlstringstatusstringerror— seeerror; the bot works without this servervalues:
"pending", "ok", "error"errorstring | nulltoolsstring[]Contract tools the bot may usechecked_atstring (date-time) | null
201Connected
idstring (uuid)urlstringstatusstringerror— seeerror; the bot works without this servervalues:
"pending", "ok", "error"errorstring | nulltoolsstring[]Contract tools the bot may usechecked_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
Request bodyrequired
urlstringrequiredlength:
≤ 2048
Request body example
{
"url": "string"
}Responses
- 204Disconnected
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 404Not found in the key's project · Error
- 422Validation failed · ValidationError
Forms
Submit a website form
post/forms/{uid}/submissions
A visitor submits a signup form of the website (popup, flyout, embedded form or bar). With double opt-in the address gets a confirmation email and becomes part of the profile only after the visitor confirms it; otherwise the email or phone, the consent and the promo code of the form are applied at once.
Used by the website forms of the tracker; not part of the SDKs.
Parameters
uidpathstringrequiredFormuidfrom the site code.length:
≤ 16
Request bodyrequired
anonymousIdstringrequiredlength:
≤ 255userIdstringlength:
≤ 255userHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.length:
≤ 128valuesobjectrequiredForm fields: email, phone, first_name, last_name, birthday (YYYY-MM-DD) and consent (boolean).languagestringlength:
≤ 35pagestringlength:
≤ 2000websitestringHidden trap field: must stay empty.variantstringA/B variant of the form the visitor saw.values:
"a", "b", "c", "d"playstringGame forms with the play-first order (stage 81): theplaytoken fromPOST /forms/{uid}/plays. The submission claims that draw; without it the server draws the prize now.length:
≤ 32
Request body example
{
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"values": {},
"language": "string",
"page": "string",
"website": "string",
"variant": "a",
"play": "string"
}Responses
201Accepted
statusstringrequiredpending— waiting for the confirmation link;accepted— applied to the profile.values:
"pending", "accepted"messagestringrequiredText for the visitor in their language.promo_codestring | nullPromo code of the form (or of the game prize) when the submission is accepted at once.prizeobject | nullGame forms (stage 81): the prize of the draw.index— the wheel sector or scratch card prize in the order ofgame.prizesof the form config;null— no prize could be drawn.keystring | nullindexinteger | nullkindstringvalues:
"promo", "text", "none"labelstringtextstring
playedbooleanGame 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.
Parameters
uidpathstringrequiredFormuidfrom the site code.length:
≤ 16
Request bodyrequired
anonymousIdstringrequiredlength:
≤ 255userIdstringlength:
≤ 255userHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.length:
≤ 128languagestringlength:
≤ 35
Request body example
{
"anonymousId": "string",
"userId": "string",
"userHash": "string",
"language": "string"
}Responses
201Drawn
playstring | nullToken for the submission;nullwhen this draw has already been claimed.prizeobject | nullrequiredGame forms (stage 81): the prize of the draw.index— the wheel sector or scratch card prize in the order ofgame.prizesof the form config;null— no prize could be drawn.keystring | nullindexinteger | nullkindstringvalues:
"promo", "text", "none"labelstringtextstring
playedbooleanrequiredThe 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.
Parameters
languagequerystringVisitor language (BCP 47).length:
≤ 35anonymousIdquerystringVisitor id: forms shown to segment members are filtered by the visitor's profile.length:
≤ 255
Responses
200OK
formsobject[]requireduidstringkindstringvalues:
"popup", "flyout", "embedded", "bar"double_opt_inbooleansettingsobjectrulesobjecttextsobject
- 401Missing, invalid or revoked key · Error
- 403The key lacks the required permission or the brand is suspended · Error
- 429Rate limit or monthly event quota exceeded · Error
Schemas
Error
messagestringrequired
ValidationError
messagestringrequirederrorsobjectrequired
IdentityRef
typestringrequiredvalues:
"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"valuestringrequiredlength:
≤ 255
IdentitiesInput
items:
1–1000
Message
typestringvalues:
"track", "identify", "page", "screen", "alias"messageIdstringlength:
≤ 100anonymousIdstring | integeruserIdstring | integeruserHashstringSignature of userId (ADR-158): HMAC-SHA256 of userId with the project's signing key ("Website → Install → Server"), hex. Computed on the site's server, never in the browser. When the project requires the signature, a userId sent with a write key without a valid userHash is ignored (the message stays with anonymousId; alias without it is dropped). Not needed with a secret key.length:
≤ 128previousIdstring | integereventstringlength:
≤ 200namestringpropertiesobjecttraitsobjectcontextobjectconsentsobject[]identify only, secret key only: marketing consents given together with the customer data (sign-up or checkout form). Unknown channels are skipped.items:
≤ 20channelstringrequiredpattern:
^[a-z0-9_]{1,64}$· example:"email"topicstringSubscription topic; the whole channel if omitted.pattern:
^[a-z0-9_-]{1,64}$statusstringrequiredvalues:
"subscribed", "unsubscribed"
timestampstring (date-time)
Profile
idintegertraitsobjectidentitiesobjectfirst_seen_atstring (date-time)last_seen_atstring (date-time)
Event
event_idstringtypestringnamestringpropertiesobjectcontextobjectoccurred_atstring (date-time)
CatalogEvent
namestringlabelstring | nullvolumeintegerfirst_seen_atstring (date-time) | nulllast_seen_atstring (date-time) | nullpropertiesobject[]keystringdata_typestring
CatalogTrait
keystringlabelstring | nulldata_typestringpiibooleansystemboolean
Segment
idintegernamestringdescriptionstring | nulltypestringvalues:
"dynamic", "static"realtimebooleanschedule_minutesinteger | nullstatusstringvalues:
"pending", "computing", "ready", "failed"sizeintegerlast_computed_atstring (date-time) | nullcreated_atstring (date-time)updated_atstring (date-time)
SegmentDetail
All fields of Segment:
rulesobject | nullRule tree: {"op": "and|or", "children": [...]}
SegmentInput
namestringrequiredlength:
≤ 120descriptionstring | nulltypestringrequiredvalues:
"dynamic", "static"realtimebooleanschedule_minutesintegervalues:
15, 30, 60, 180, 360, 720, 1440rulesobject
SegmentPatch
namestringlength:
≤ 120descriptionstring | nullrealtimebooleanschedule_minutesintegerrulesobject
Journey
idintegernamestringdescriptionstring | nullstatusstringvalues:
"draft", "active", "paused", "archived"versioninteger | nullnext_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.values:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
JourneyDetail
All fields of Journey:
draftobjectgraphobjectentryobject
publishedobject | nullgraphobjectentryobject
JourneyInput
namestringrequiredlength:
≤ 120descriptionstring | nullgraphobjectnodesarrayitems:
≤ 200edgesarrayitems:
≤ 400
entryobject
JourneyPatch
namestringlength:
≤ 120descriptionstring | nullgraphobjectentryobject
Enrollment
idintegerprofile_idintegerversion_idintegerstatusstringcurrent_node_idstring | nullexit_reasonstring | nullentered_atstring (date-time)finished_atstring (date-time) | nullgoal_reached_atstring (date-time) | null
EnrollResult
enrolledbooleanenrollment_idinteger | nullprofile_idinteger
CampaignAudience
segment_idsinteger[]requiredMembers of any of these segments get the campaign.items:
≤ 10exclude_segment_idsinteger[]Members of these segments are excluded.items:
≤ 10ignore_control_groupbooleanSend to the global control group too (ADR-167). By default profiles of the control group get no marketing messages.
CampaignVariant
keystringrequiredpattern:
^[a-z0-9_]{1,32}$template_idinteger | nullMessage template of the campaign channel.percentintegerrequiredShare of the audience (or of the A/B test share); all variants add up to 100.range:
1–100
CampaignAb
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.modestringvalues:
"test", "auto"· default:"test"test_percentintegerrange:
5–50metricstringrequiredvalues:
"opened", "clicked", "goal"waitobjectamountintegerrange:
1–72unitstringvalues:
"hour", "day"
CampaignSchedule
local_time — in each recipient's timezone trait; with best_time — at each recipient's best hour within 24 hours of the start.typestringrequiredvalues:
"now", "at", "recurring"atstringForat: Y-m-d\TH:i.example:
"2026-11-01T10:00"repeatstringvalues:
"daily", "weekly", "monthly"timestringexample:
"10:00"weekdaysinteger[]ISO weekdays forweekly(1 = Monday).day_of_monthintegerrange:
1–28start_datestring (date) | nullend_datestring (date) | nulllocal_timebooleanbest_timebooleanSend to each recipient at theirbest_send_hourtrait (predictions) within 24 hours of the start; without it — at the project best hour, otherwise right away. Requires predictions in the plan; not combined withlocal_time.
CampaignGoal
eventstringrequiredwithinobjectrequiredamountintegerrange:
1–90unitstringvalues:
"hour", "day"
Campaign
idintegernamestringdescriptionstring | nullstatusstringvalues:
"draft", "scheduled", "sending", "sent", "paused", "cancelled"integration_idinteger | nullchannelstring | nullaudienceCampaignAudiencevariantsCampaignVariant[]scheduleCampaignSchedulerate_per_minuteinteger | nullgoalCampaignGoalnext_run_atstring (date-time) | nulllast_run_atstring (date-time) | nullapproval_statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.values:
"pending", "approved", "returned"created_atstring (date-time)updated_atstring (date-time)
CampaignInput
namestringrequiredlength:
≤ 120descriptionstring | nullintegration_idinteger | nullChannel integration; the template of every variant must belong to its channel.items:
1–5rate_per_minuteinteger | nullrange:
10–100000goalCampaignGoal
CampaignVariantStats
queuedintegersentintegerdeliveredintegeropenedintegerclickedintegerbouncedintegerfailedintegerskippedintegerunsubscribedintegerconvertedinteger | nullRecipients with the goal event in the window; null without a goal.
CampaignRun
idintegerstatusstringvalues:
"preparing", "sending", "testing", "completed", "paused", "cancelled", "failed"scheduled_atstring (date-time)started_atstring (date-time) | nullfinished_atstring (date-time) | nullaudience_sizeintegerRecipients without the control group.held_outintegerRecipients in the global control group: no message was sent to them.controlobject | nullRecipients of the run in the control group: no message,$message_skippedwith reasoncontrol_groupat the time the message would have been sent; goal conversion within the same window. null — no control group in the run.profilesintegerconvertedinteger | nullnull — the campaign has no goalstatsAbStatsGoal conversion: armcontrolagainst armcampaign(sent messages)
queuedintegerwinnerstring | nullwinner_atstring (date-time) | nullerrorstring | nullauto_pausedobject | nullSet 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)sentintegercomplaint_ratenumberPercentbounce_ratenumberPercentexceededstring[]limitsobjectcomplaint_ratenumberbounce_ratenumber
variantsobjecttotalCampaignVariantStatsmetricstringvalues:
"opened", "clicked", "goal"statsAbStatsab_resultobject | nullTest result saved when the A/B winner was picked.metricstringdecided_atstring (date-time)statsAbStats
languagesobjectResults per language of the sent template version.
AbStats
verdictstringvalues:
"winner", "no_difference", "insufficient_data"winnerstring | nullSet only when the best variant is significantly better than every other one.beststringrequired_per_arminteger | nullalphanumberarmsobject[]keystringtrialsintegersuccessesintegerratenumbercinumber[]Wilson 95 % intervalitems:
2–2liftnumber | nullRelative to the first variantp_valuenumber | nullHolm-adjusted p-value against the best variantprobability_bestnumber
ProductCard
idstringnamestringurlstring | nullimagestring | nullJPEG up to image_width via imgproxy; without imgproxy — a direct link (CDN copy or feed URL).image_originalstring | nullDirect link: the platform CDN copy if the feed mirrors images, otherwise the feed URL.srcsetobject | nullVariants for: AVIF and WebP srcset (240–960 px); null without imgproxy. avifstringwebpstring
pricenumber | nullold_pricenumber | nullcurrencystring | nullbrandstring | nullcategory_idstring | nullmin_quantityinteger | nullThe product is sold as a set (tires by 4): how many to add to the cart; null — one.ratingnumber | nullAverage score of published reviews;nullwithout reviews.reviews_countintegerNumber of published reviews.
ProductInput
idstringrequiredProduct id on the site: product_id in events.length:
≤ 128namestringrequiredlength:
≤ 500urlstring (uri)imagestring (uri)pricenumberrange:
≥ 0old_pricenumberrange:
≥ 0currencystringlength:
3–3availablebooleandefault:
truestockintegerUnits in stock. Used only when "Use stock levels from the API and plugins" is on in the catalog settings of the project: then the stock is saved, zero takes the product off sale, and the "low stock" journey trigger works. Otherwise it is ignored.range:
≥ 0category_idsstring[]Leaf category first.items:
≤ 10brandstringlength:
≤ 200descriptionstringProduct description, plain text or HTML (ADR-132). HTML is turned into text and the result is cut to 5000 characters; the AI answers shoppers' questions about the product from it.length:
≤ 65535paramsobjecttranslationsobjectTranslations by language (BCP 47 tag → text), ADR-080: name, url and params in that language; they are shown to visitors and in messages of the language. Languages sent before are kept, a new one is added.keys:
≤ 20
MessageTemplate
idintegernamestringchannelstringexample:
"email"topicstringSubscription topic the message belongs to.transactionalbooleanlanguagestringMain language ofcontent: recipients whose profile language has no version get it.length:
≤ 16· example:"de"contentobjectFields of the channel message schema, e.g.subject,htmlandtextfor email; string fields are Twig templates.translationsobjectOther language versions: language tag → content. A recipient gets the version for thelanguageprofile trait (exact tag, then the base language, then another variant of it), otherwisecontent.versionintegerGrows when any language version changes.created_atstring (date-time) | nullupdated_atstring (date-time) | null
MessageTemplateInput
namestringrequiredlength:
≤ 120channel_keystringrequiredChannel of the template; cannot be changed later.topicstringdefault:
"marketing"· length:≤ 64· pattern:^[a-z0-9_-]+$transactionalbooleandefault:
falselanguagestringMain language ofcontent; the project default language if omitted.length:
≤ 16· example:"de"contentobjectrequiredFields of the channel message schema, e.g.subject,htmlandtextfor email; string fields are Twig templates.translationsobjectOther language versions; each is validated likecontent. Omit to keep the stored versions, pass{}to delete them.keys:
≤ 50
AnalyticsReportType
string
values: "report", "funnel", "retention", "paths", "revenue", "traffic", "attribution", "ropo", "assistants"
AnalyticsPeriod
One of:
lastintegerrequiredLast N days including today, in the project timezonevalues:
7, 14, 30, 90, 180, 365
fromstring (date)requiredtostring (date)required
Dates in the project timezone, up to 731 days
PropertyFilter
keystringrequiredProperty key from the event catalogoperatorstringrequiredOperator of the property type, as in segment rulesvalueanyValue for the operator; absent for is_set / is_not_set
ProfileRules
An object with arbitrary keys.
Breakdown
sourcestringrequiredvalues:
"property", "context"keystringrequiredEvent property, or a page field: page.path, page.referrer, campaign.source, campaign.medium, campaign.name, localelimitintegerEvent reports only: how many values are shown separately, the rest go to $other. Funnels always show 10.values:
5, 10· default:10
AnalyticsInterval
string
values: "day", "week", "month"
ReportQuery
seriesobject[]requireditems:
1–5eventstring | nullmetricstringvalues:
"count", "profiles", "per_profile", "sum", "avg"propertystring | nullfiltersPropertyFilter[]
profilesProfileRulesbreakdownBreakdownintervalAnalyticsIntervalperiodAnalyticsPeriodcompareboolean
FunnelQuery
stepsobject[]requireditems:
2–10eventstringrequiredfiltersPropertyFilter[]
windowobjectConversion window from the first step, up to 90 daysamountintegerrange:
≥ 1unitstringvalues:
"minute", "hour", "day"
orderstringvalues:
"sequential", "strict"profilesProfileRulesbreakdownBreakdownperiodAnalyticsPeriod
RetentionQuery
startobjectrequiredeventstring | nullfiltersPropertyFilter[]
returnobjecteventstring | nullfiltersPropertyFilter[]
cohortstringvalues:
"first", "period"intervalAnalyticsIntervalperiodsintegerUp to 30 days, 12 weeks or 12 monthsrange:
1–30returnsstringvalues:
"exact", "rolling"profilesProfileRulesperiodAnalyticsPeriod
PathQuery
eventstringrequiredfiltersPropertyFilter[]directionstringvalues:
"after", "before"stepsintegerrange:
1–5gap_minutesintegerrange:
1–1440excludestring[]items:
≤ 20profilesProfileRulesperiodAnalyticsPeriod
RevenueQuery
eventstringPurchase event; by default from the prediction settingsamountstringNumeric order amount propertyproduct_propertystringintervalAnalyticsIntervalltv_intervalstringvalues:
"week", "month"ltv_periodsintegerrange:
1–12profilesProfileRulesperiodAnalyticsPeriod
TrafficQuery
dimensionstringvalues:
"channel", "source", "source_medium", "campaign", "referrer", "landing"intervalAnalyticsIntervaleventstringamountstringprofilesProfileRulesperiodAnalyticsPeriod
AttributionQuery
window_daysintegervalues:
1, 3, 7, 14, 30modelstringvalues:
"last", "first", "linear"intervalAnalyticsIntervaleventstringamountstringprofilesProfileRulesperiodAnalyticsPeriod
ReportResult
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
bucketsstring (date)[]requiredseriesobject[]requiredPer series: index, total, values per bucket, previous period, breakdown
FunnelResult
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
stepsobject[]requiredPer step: event, reached, from_start, from_previous, median_seconds, avg_secondsbreakdownobject[]requiredPer breakdown value: value, steps (reached per step)time_samplenumberShare of profiles used for time between steps
RetentionResult
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
cohortsobject[]requiredPer cohort: date, size, values (returned per period, null — not yet), open (period still running)averageobject[]requiredPer period: period, rate, profiles
PathResult
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
totalintegerrequirednodesobject[]requiredlinksobject[]requiredpathsobject[]requiredMost frequent paths: events, profilestruncatedboolean
RevenueResult
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
currencystring | nullother_currency_ordersintegersummaryobjectrequiredseriesobjectrequiredltvobjectrequiredproductsobject[]requiredcategoriesobject[]required
TrafficResult
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
currencystring | nullpurchasesbooleansummaryobjectrequiredrowsobject[]requiredrow_countintegerchartobjectrequired
AttributionResult
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
currencystring | nullsummaryobjectrequiredchannelsobject[]requiredPer channel: channel, clicks, touched_orders, revenue and orders by modelitemsobject[]requiredPer campaign, journey, message channel or widgetchartobject
SavedReport
idintegerrequirednamestringrequiredcreated_atstring (date-time)requiredupdated_atstring (date-time)required
SavedReportDetail
All fields of SavedReport:
definitionobjectrequiredviewobjectrequiredPage view settings: chart type, metric
SavedReportInput
namestringrequiredlength:
≤ 120definitionobjectrequiredDefinition of the report type — see the run operationsviewobject
SavedReportPatch
namestringlength:
≤ 120definitionobjectviewobject
Dashboard
idintegerrequirednamestringrequiredlayoutobject[]requireditems:
≤ 24report_idintegerrequiredsizestringvalues:
"half", "full"
mainbooleanrequiredThe 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)requiredupdated_atstring (date-time)required
DashboardInput
namestringrequiredlength:
≤ 120layoutobject[]items:
≤ 24report_idintegerrequiredsizestringvalues:
"half", "full"
periodAnalyticsPeriodmainbooleantrue makes the dashboard main (the previous main dashboard stops being main). The flag cannot be cleared: make another dashboard main instead.
DashboardPatch
namestringlength:
≤ 120layoutobject[]items:
≤ 24report_idintegerrequiredsizestringvalues:
"half", "full"
periodAnalyticsPeriodmainbooleantrue makes the dashboard main (the previous main dashboard stops being main). The flag cannot be cleared: make another dashboard main instead.
LoyaltyProfileRef
typestringrequiredvalues:
"user_id", "anonymous_id", "email", "phone", "loyalty_card", "telegram_chat_id", "viber_id", "max_user_id", "vk_user_id", "instagram_id", "facebook_psid", "web_push"valuestringrequired
LoyaltyAccount
memberbooleanbalanceintegerAvailable pointspendingintegerPoints waiting for the return periodtierstring | nulltier_spendnumberexpiringintegerPoints expiring within 30 daysexpires_atstring (date-time) | nullenrolled_atstring (date-time) | nullreferral_codestring | nullCode of the member for inviting friends.referral_urlstring | nullReferral link (?ref=on the store page) when referrals are on.referralsobjectFriends who came with the code, of them rewarded, and points for them.invitedintegerrewardedintegerpointsinteger
LoyaltyCalculation
memberbooleanbalanceintegertierstring | nullmax_pointsintegermax_discountnumberearn_pointsintegerpoint_valuenumbercurrencystring | null
LoyaltyRedemption
idstringstatusstringvalues:
"held", "confirmed", "cancelled", "expired"pointsintegerreturnedintegerdiscountnumbercart_idstringorder_idstring | nullheld_untilstring (date-time)confirmed_atstring (date-time) | null
LoyaltyTransaction
idintegertypestringvalues:
"earn", "cancel", "expire", "adjust", "redeem", "refund"pointsintegerreferencestring | nullreasonstring | nullrulestring | nullcreated_atstring (date-time)referralstring | nullReferral reward:friend— for joining by invitation,referrer— for the first order of a friend.values:
"friend", "referrer", null
PromoPool
keystringrequirednamestringrequiredtypestringrequiredshared— one code for everyone;unique— a separate code for every profile.values:
"shared", "unique"statusstringrequiredvalues:
"active", "paused"activebooleanrequiredActive now: not paused and within the promotion period.discountstring | nullDiscount text for messages, e.g. «−10 %». The discount itself is a coupon rule of the store.starts_atstring (date-time) | nullends_atstring (date-time) | nullEnd of the promotion (exclusive).validity_daysinteger | nullA code is valid for this many days after it is issued (not longer than the promotion).per_profileintegerrequiredHow many codes of the pool one profile can receive.statsobjectrequiredtotalintegeravailableintegerissuedintegerusedintegerusesintegerrevenuenumberSum of the orders with codes of the pool.
PromoCode
poolstringPool key.codestringrequiredstatusstringrequiredvalues:
"available", "issued", "used", "shared"issued_atstring (date-time) | nullexpires_atstring (date-time) | nullused_atstring (date-time) | null
LoyaltyReferral
statusstringpending— waiting for the friend's first order.values:
"pending", "rewarded", "expired", "limit", "cancelled"codestringfriend_pointsintegerfriend_promo_codestring | nullrewardedbooleanThe friend has received the reward.expires_atstring (date-time)The first order of the friend rewards the member until this moment.
MessageSendInput
template_id (and integration_id if needed) for one message, or steps for a cascade — not both.- The recipient. A profile with this identity is created if there is none.
traitsobjectTraits written to the profile before sending, available in the template astraits.*.keys:
≤ 100template_idintegerMessage 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 | nullChannel integration of the template's channel; may be omitted when the channel has exactly one active integration.dataobjectPer-message data, available in the template ascontext.data.*(order number, confirmation code).stepsCascadeStep[]Cascade (plans with thecascadesfeature): channels tried in order — the next one when the profile cannot be reached on the previous, or its message was not sent, not delivered or not read within the step time.items:
2–5
MessageStatus
idstring (uuid)statusstringqueued→sent→delivered;scheduled— waiting (quiet hours, warm-up);skipped— not sent, seereason;failed/bounced— seereasonanderror.values:
"queued", "scheduled", "sent", "delivered", "failed", "skipped", "bounced"reasonstring | nullWhy 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 | nullchannelstringtemplate_idinteger | nullintegration_idinteger | nullprofile_idintegertransactionalbooleanoriginstring | nullapifor messages sent withmessages.send,storefor store emails (emails.send).created_atstring (date-time) | nullscheduled_forstring (date-time) | nullsent_atstring (date-time) | nulldelivered_atstring (date-time) | nullopened_atstring (date-time) | nullclicked_atstring (date-time) | nullfailed_atstring (date-time) | null
CascadeStep
integration_idintegerrequiredtemplate_idintegerrequiredTemplate of the integration's channel.wait_forstringWhat counts as success.deliveredneeds an integration that reports delivery (not email through own SMTP),opened— a channel that reports reading (email, WhatsApp, Viber).values:
"sent", "delivered", "opened"· default:"sent"timeoutobjectHow long to wait fordeliveredoropenedafter sending; 15 minutes by default.amountintegerrange:
1–3650unitstringvalues:
"minute", "hour", "day", "week"
CascadeStatus
idstring (uuid)statusstringreached— a step succeeded;failed— no channel reached the profile.values:
"running", "reached", "failed"stepintegerCurrent step, from 0.reached_channelstring | nullprofile_idintegeroriginstring | nullcreated_atstring (date-time) | nullfinished_atstring (date-time) | nullmessagesMessageStatus[]Messages of the steps tried so far.
ChatVisitorMessage
idintegerauthorstringvalues:
"visitor", "operator", "system"bodystringoperatorstring | nullFirst name of the operatoractionstring | nullclosed — the conversation was closedcreated_atstring (date-time)botbooleanReply of the AI bot; operator holds the bot nameimagesobject[]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 | nullwidthinteger | nullheightinteger | nullstatusstringvalues:
"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 firstchecking(no url) and thenreadyorfailed; the change comes as the realtime eventmessage.updatedwith the whole message.namestringsizeinteger | nullurlstring | nullstatusstringvalues:
"pending", "checking", "ready", "failed", "expired"errorstring | nullWhy afaileddocument 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 messageproductsobject[]Catalog product cards of an operator message (stage 97)idstringnamestringurlstring | nullimagestring | nullpricenumber | nullcurrencystring | nullavailableboolean
ChatVisitorConversation
idstring (uuid)statusstringvalues:
"open", "waiting", "closed"ratinginteger | nulltokenstringReturned for a new conversation or when the request had no valid token; store itbotbooleanThe AI bot leads the conversation: the widget offers to call an operator (POST /chat/handoff)queueinteger | nullPlace in the operators' queue (1 — next) while the conversation waits for an operator with automatic routing; null otherwise
Conversation
idstring (uuid)requiredprofile_idintegerrequiredchannelstringrequiredweb— the website chat; messengers need thechat_messengersplan feature.values:
"web", "telegram", "whatsapp", "viber", "max", "vk", "instagram", "messenger", "email"statusstringrequiredopen— the customer wrote last and waits for an answer;waiting— answered, waiting for the customer;closed.values:
"open", "waiting", "closed"assignedbooleanrequiredAn operator is responsible for the conversation.unread_countintegerrequiredCustomer messages operators have not read yet.languagestring | nullproduct_idstring | nullLast product the customer asked about from the site (product question widget or a product page), id in the catalogtagsstring[]Tag names from the project tag dictionary, set by operators (stage 97)ratinginteger | nullCustomer rating after the conversation.range:
1–5rating_commentstring | nulllast_message_atstring (date-time) | nulllast_message_authorstring | nullvalues:
"visitor", "operator", "system", nullfirst_reply_atstring (date-time) | nullcreated_atstring (date-time)requiredclosed_atstring (date-time) | null
ConversationMessage
idintegerrequiredauthorstringrequiredvisitor— the customer;operator— an answer from the inbox or the API;system— assignment, closing and reopening (seeaction).values:
"visitor", "operator", "system"viastring | nullWhere an answer or action came from: the operator inbox or the API.values:
"inbox", "api", nullapi_keystring | nullName of the API key that answered or closed the conversation.bodystringrequiredMessage text; empty for system messages except notesactionstring | nullAction of a system message; note — an internal note for operators (body is its text), never shown to the customervalues:
"assigned", "unassigned", "routed", "transferred", "closed", "reopened", "bot_handoff", "store_action", "note", nullproduct_idstring | nullProduct the customer asked about with this message, id in the catalogstatusstring | nullDelivery status of an answer sent to a messenger: queued, sent, delivered, failed, skipped, bounced.created_atstring (date-time)requiredimagesobject[]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)statusstringvalues:
"ready", "pending", "failed", "expired"urlstring (uri) | nullwidthinteger | nullheightinteger | 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 firstpending(downloading from the messenger) orchecking(stored, checked for active content and by the antivirus in the background) without url, thenreadyorfailed; themessage.createdwebhook carries the first state.idstringstatusstringvalues:
"pending", "checking", "ready", "failed", "expired"namestringmimestring | nullsizeinteger | nullurlstring | null
buttonsstring[]Quick reply buttons of the reply (stage 97)productsobject[]Product cards of the reply (stage 97)idstringnamestringurlstring | nullpricenumber | nullcurrencystring | null
ConversationDetail
All fields of Conversation:
- The latest messages, oldest first.
StoreEmailInput
tostring (email)requiredRecipient address. The profile is found by this email or created.length:
≤ 254subjectstringRequired unless an order template is enabled forkindandorderis given.length:
≤ 998htmlstringReady HTML of the store email. Sent as is: it is not a template, braces are not processed. Required unless an order template is enabled forkindandorderis given.length:
≤ 1000000textstring | nullPlain-text part; built from the HTML when empty.length:
≤ 1000000reply_tostring (email) | nullOverrides the Reply-To of the email integration.from_namestring | nullOverrides the sender name of the email integration; the sender address is always the integration's.length:
≤ 100kindstringrequiredWhat 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. Fororder_placed,order_paid,order_shipped,order_delivered,order_cancelled,order_refundedwithorder, an enabled OneTrace template builds the email instead ofhtml(seeGET /emails/settings).pattern:
^[a-z0-9_]{1,40}$languagestring | nullCustomer language tag: picks the language version of an order template; for history and reports otherwise.length:
≤ 20integration_idinteger | nullEmail integration; may be omitted when the project has exactly one active.traitsobject | nullProfile traits to update before sending (name, phone).attachmentsobject[]Up to 5 files, 5 MB in total.items:
≤ 5namestringrequiredlength:
≤ 200typestringrequiredvalues:
"application/pdf", "image/png", "image/jpeg", "image/gif", "text/plain", "text/csv", "text/calendar"contentstring (byte)requiredFile contents in base64.
orderStoreOrder
StoreEmailStatus
All fields of MessageStatus:
kindstring | nulltemplatebooleanThe email is built from a OneTrace order template.
StoreOrder
order template variable.order_idstringrequiredlength:
≤ 100numberstring | nullNumber shown to the customer;order_idwhen empty.length:
≤ 100urlstring (uri) | nullOrder page for the customer.created_atstring (date-time) | nullcurrencystringrequiredpattern:
^[A-Za-z]{3}$amountnumberrequiredOrder total.subtotalnumber | nulldiscountnumber | nullshippingnumber | nulltaxnumber | nullrefund_amountnumber | nullcouponstring | nullpayment_methodstring | nullshipping_methodstring | nullcarrierstring | nulltracking_numberstring | nulltracking_urlstring (uri) | nullestimated_deliverystring (date) | nullreasonstring | nullCancellation or refund reason.notestring | nullpayment_instructionsstring | nullBank transfer details and similar instructions.productsobject[]items:
≤ 100product_idstring | nullvariant_idstring | nullskustring | nullproduct_namestringrequiredlength:
≤ 300quantitynumberrequiredpricenumberrequiredtotalnumber | nullLine total; price × quantity when empty.image_urlstring (uri) | nullurlstring (uri) | nulloptionsstring | nullVariant options as text: «Size: M, colour: white».length:
≤ 500
shipping_addressobject | nullnamestring | nulllength:
≤ 200companystring | nulllength:
≤ 200address1string | nulllength:
≤ 200address2string | nulllength:
≤ 200citystring | nulllength:
≤ 200regionstring | nulllength:
≤ 200postcodestring | nulllength:
≤ 200countrystring | nulllength:
≤ 200phonestring | nulllength:
≤ 200
billing_addressobject | nullnamestring | nulllength:
≤ 200companystring | nulllength:
≤ 200address1string | nulllength:
≤ 200address2string | nulllength:
≤ 200citystring | nulllength:
≤ 200regionstring | nulllength:
≤ 200postcodestring | nulllength:
≤ 200countrystring | nulllength:
≤ 200phonestring | nulllength:
≤ 200
StoreEmailSettings
relaybooleanSend all store emails through OneTrace (store emails section).integration_idinteger | nulltemplatesobjectOrder email kinds built from OneTrace templates: the store does not send its own email for them and passesorderinstead.
StoreMcpServer
idstring (uuid)urlstringstatusstringerror— seeerror; the bot works without this servervalues:
"pending", "ok", "error"errorstring | nulltoolsstring[]Contract tools the bot may usechecked_atstring (date-time) | null
ProfilePreferences
profile_idintegerlanguagestringLanguage of topic names.example:
"en"channelsobject[]Channels the profile receives or can receive messages in: channels of its consents and messages of the last year, and channels of active integrations it has an address for.keystringexample:
"email"namestringName of the channel in the requested language, lower case as inside a sentence.example:
"email"blockedbooleanHard block (the address does not exist, the bot was stopped): read only.
unsubscribed_allbooleanThe profile unsubscribed from marketing messages in all channels (unsubscribe_allor the preference center): channels without their own subscription stay closed.adsboolean | nullAdvertising consent;null— the project has no ad platform connected, nothing to ask.topicsobject[]Visible subscription topics.keystringexample:
"news"namestringdescriptionstringchannelsobjectChannel key → subscribed (true/false),null— the topic is not offered in this channel.
frequencystring | nullAt most one marketing message per week or month across channels;null— as usual.values:
"weekly", "monthly", nullpaused_untilstring (date-time) | nullMarketing 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
idstringrequiredStore id — the value ofstore_idin offline checks.length:
≤ 128namestringrequiredlength:
≤ 200citystring | nulllength:
≤ 120addressstring | nulllength:
≤ 300
RopoQuery
window_daysintegerOnline touches no earlier than this many days before the in-store check (default 30)values:
1, 3, 7, 14, 30, 60, 90touchesstring[]Kinds of online touches: website visit (source — traffic channel), product view, message click (default — all)intervalAnalyticsIntervaleventstringPurchase event (default — from the project settings)amountstringNumeric amount property of the purchase eventproduct_propertystringProduct id property in products[] lines (default — from the recommendation settings)profilesProfileRulesperiodAnalyticsPeriod
RopoResult
definitionobjectrequiredNormalized definitionpendingbooleanOnly in a 202 response: the report of a large project is being calculated in the queue — repeat the request laterperiodobjectfromstring (date)tostring (date)
currencystring | nullwindow_daysintegertouchesstring[]product_viewsbooleanThe project has a product view event: products are matched to viewssummaryobjectoffline_revenue, offline_orders, offline_buyers, ropo_revenue, ropo_orders, ropo_buyers, ropo_share, ropo_orders_share, online_revenue, online_orders, median_dayscomparisonobjectropo and offline_only customers: buyers, orders, revenue, aov, orders_per_buyer, revenue_per_buyerreverseobjectOnline orders after an in-store purchase within the window (showrooming): online_orders, online_revenue, orders, revenue, buyers, sharesourcesobject[]Per touch source: kind (visit or message), channel, orders, revenue, buyers, share. A check counts towards every source in its windowstoresobject[]Per store: id, name, city, orders, revenue, buyers, ropo_orders, ropo_revenue, ropo_share, aov, ropo_aov, other_aov, showroom_orders, showroom_revenueproductsobject[]Products viewed online and bought in store (top 20): id, name, orders, viewed_orders, viewed_sharedaysobject[]Checks with a touch by days from the first touch: from, to, orders, revenuechartobjectbuckets, ropo_revenue, other_offline_revenue, showroom_revenue
ControlGroupPeriod
idintegerpercentintegerShare of profiles in the control group, %range:
1–50started_atstring (date-time)ended_atstring (date-time) | nullnull for the active period
ControlGroupSide
profilesintegerbuyersintegerordersintegerrevenuenumberconversionnumber | nullBuyers / profilesrevenue_per_profilenumber | nullaovnumber | nullAverage order value
ControlGroupReport
periodControlGroupPerioduntilstring (date-time)End of the calculation: the end of the period or the next full hour for the active onecurrencystring | nulleventstringPurchase event from the revenue settings of the projectgroupsobjectcontrol— profiles of the control group,target— everyone elsecontrolControlGroupSidetargetControlGroupSide
conversionAbStatsrevenue_per_profileobject | nullWelch z-test of revenue per profile, target against control; null with fewer than 30 profiles in a groupcontrolnumberMean revenue per profile of the control grouptreatmentnumberMean revenue per profile of everyone elsedifferencenumbercinumber[]95 % interval of the differenceitems:
2–2liftnumber | nullp_valuenumbersignificantboolean
incrementalobjectEffect of the communications: (target per profile − control per profile) × target profilesrevenuenumberrevenue_cinumber[] | nullitems:
2–2ordersintegerbuyersinteger
other_currency_ordersintegerOrders in another currency, not countedheld_messagesintegerMarketing messages not sent to the control group in the periodseriesobjectCumulative incremental revenue by day (by week for periods longer than 120 days)intervalstringvalues:
"day", "week"bucketsstring (date)[]incremental_revenuenumber[]controlnumber[]Cumulative revenue per profiletargetnumber[]
exemptobjectCampaigns and journeys of the period with «send to the control group too»: the effect is understatedcampaignsobject[]idintegernamestring
journeysobject[]idintegernamestring
LaunchReadiness
readybooleanrequiredNo errors: the launch will pass.clearbooleanrequiredNo errors and no warnings.checksobject[]requiredkeystringrequiredconfig, archived, quota, sending_domain, integration, untranslated, template_error, unsubscribe, deliverability, segment_pending, segment_empty, segment_broad, goal_missing, goal_unseen, goal_windowlevelstringrequiredvalues:
"error", "warning", "info"messagestringrequiredText in the language of the requestpathstringField of a config error, e.g.variants.0.template_id
EventSchema
enabledbooleanCheck incoming events against the schemaeventsobject[]items:
≤ 1000namestringrequiredEvent name (system$…events are not allowed)length:
≤ 255labelstring | nulllength:
≤ 255descriptionstring | nulllength:
≤ 1000propertiesobject[]items:
≤ 200keystringrequiredlength:
≤ 255typestringrequiredvalues:
"string", "number", "boolean", "datetime", "list", "object"requiredbooleandefault:
falsevaluesstring | number[] | nullAllowed values (strings or numbers; only forstringandnumberproperties)items:
≤ 100One of:
descriptionstring | nulllength:
≤ 1000
EventSchemaViolation
kindstringvalues:
"unplanned_event", "unplanned_property", "missing_property", "wrong_type", "unexpected_value"eventstringpropertystring | nullcountintegerlast_atstring (date-time)examplestring | null
Approval
requiredbooleanThe project requires approval before launch.statusstringApproval status when the project requires approval before launch: pending (on review), approved, returned (sent back with a comment); null — never submitted.values:
"pending", "approved", "returned"approved_bystringapproved_atstring (date-time)changedbooleanApproved, but changed since approval: launch will send it back to review.historyobject[]actionstringvalues:
"requested", "approved", "returned", "changed"commentstringuserstringvia_apibooleanatstring (date-time)
AssistantsQuery
intervalAnalyticsIntervaleventstringPurchase event; defaults to the purchase event of the project settings. Without it the report has no purchasesamountstringNumeric property with the order amountperiodAnalyticsPeriod
AssistantsResult
definitionobjectrequiredNormalized definitionperiodobjectrequiredfromstring (date)tostring (date)
currencystring | nullpurchasesbooleanattribution_daysintegersummaryobjectrequiredcurrentandpreviousperiod: requests, searches, product_clicks, carts, cart_clicks, assistant_orders, visits, visitors, orders, revenueassistantsobject[]requiredchartobjectrequiredbucketsand per assistantrequestsandvisitsby bucketqueriesobject[]requiredquerystringcountintegeremptyintegerSearches without results
productsobject[]requiredidstringnamestring | nullrequestsintegerclicksinteger