> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Track Experience Events
> This API tracks impressions (shown) and user interactions (clicked) for accurate experience reporting. To report an impression or click for your experience via API, use the following endpoint.
If you do not call this endpoint, your MoEngage analytics dashboard will show zero impressions and zero clicks, and campaign reporting will be empty.
## OpenAPI
````yaml /api/personalize-experience/personalize-experience.yaml post /experiences/events
openapi: 3.0.3
info:
title: Personalize APIs
description: >
Personalize APIs constitute a set of endpoints that can be accessed from
your platform's code. These APIs offer personalization capabilities and must
be invoked from your codebase for MoEngage to provide relevant data. After
receiving the data, you can use it within your platform's code to
personalize the content for your users.
version: 1.0.0
servers:
- url: https://sdk-{dc}.moengage.com/v1
description: MoEngage API Server
variables:
dc:
default: '01'
description: >-
The ‘dc’ in the API Endpoint URL refers to the MoEngage Data Center
(DC). MoEngage hosts each customer in a different DC. You can find
your DC number and replace the value of ‘dc’ in the URL by referring
to the DC and API endpoint mapping
[here](/api/introduction#data-centers). Your MoEngage Data Center (DC)
can be 01, 02, 03, 04, 05, 06, or 101.
security:
- basicAuth: []
tags:
- name: Experiences
description: API endpoints for fetching experiences and metadata.
- name: Events
description: API endpoints for reporting impressions and clicks.
paths:
/experiences/events:
post:
tags:
- Events
summary: Track Experience Events
description: >
This API tracks impressions (shown) and user interactions (clicked) for
accurate experience reporting. To report an impression or click for your
experience via API, use the following endpoint.
operationId: reportExperienceEvents
parameters:
- name: MOE-APPKEY
in: header
required: true
description: >-
This is the Workspace ID of your MoEngage account that must be
passed with the request. You can find it in the MoEngage dashboard
at **Settings** > **Account** > **APIs** > **Workspace ID (earlier
app id)**.
schema:
type: string
example: Workspace ID
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
elements:
type: array
maxItems: 100
description: >-
Array of user-event objects. Each element represents one
user. You can batch up to 100 users per request.
items:
type: object
properties:
customer_id:
type: string
description: >
Your brand provides this field, which should be pasted
in the request. Generally, this is the phone number,
email ID, or any other unique ID used to uniquely
identify the user in MoEngage. This is essential for
event mapping back to the user.
If the **customer_id** shared is not present in
MoEngage, a new user profile will be created with the
shared details.
user_attributes:
type: object
description: >
This field is used to update the details of a user
identified by **customer_id**.
If the **customer_id** does not exist, a new user will
be created with the details present in
**user_attributes**.
user_timezone_offset:
type: integer
description: >
The user's UTC offset **in seconds** (not minutes, not
hours). Used for time-based analytics segmentation.
Valid range: `-54000` to `54000`.
**Common values**:
- UTC: `0`
- IST (UTC+5:30): `19800`
- US Eastern (UTC−5): `-18000`
- US Pacific (UTC−8): `-28800`
minimum: -54000
maximum: 54000
actions:
type: array
description: >-
Multiple actions or events performed by a user can be
grouped together in a single API call.
items:
type: object
properties:
action:
type: string
description: >
This field identifies the action or the event
performed by the user. The value is
case-sensitive — any other string returns a
`400` error.
**Accepted values**:
- `MOE_PERSONALIZATION_MESSAGE_SHOWN` — send
immediately after the personalized component
becomes visible to the user.
- `MOE_PERSONALIZATION_MESSAGE_CLICKED` — send
when the user clicks or taps the personalized
component.
enum:
- MOE_PERSONALIZATION_MESSAGE_SHOWN
- MOE_PERSONALIZATION_MESSAGE_CLICKED
moe_event_uuid:
type: string
format: uuid
description: >
Unique UUID v4 identifier for each event
occurrence. Used by MoEngage for server-side
deduplication.
- **On first attempt**: generate a fresh UUID.
- **On retry**: reuse the same UUID from the
original attempt — MoEngage will deduplicate it
and not double-count the event.
- **Never reuse** a UUID across different
events.
Generate with: `uuid.uuid4()` (Python),
`uuidv4()` (Node.js), `UUID.randomUUID()`
(Java).
event_time:
type: integer
description: >
Unix timestamp of the event **in seconds** (not
milliseconds).
Generate with:
- JavaScript: `Math.floor(Date.now() / 1000)`
- Python: `int(time.time())`
- Java: `Instant.now().getEpochSecond()`
platform:
type: string
description: >
The platform on which the user is shown the
personalization event. If the value is missing
or unrecognized, **Unknown** is used.
**Accepted values**: `web`, `android`, `ios`,
`tv`. Matching is case-insensitive (`Android`,
`iOS`, and `Web` all work). Use lowercase for
consistency with existing examples.
attributes:
type: object
description: >
Pass-through of the `experience_context` object
returned by the [Fetch
Experience](/api/experiences/fetch-experience)
API. Store `experience_context` from the fetch
response and copy each field into `attributes`
here when the user sees or clicks the experience
— for example, `experience_context.cid` becomes
`attributes.cid`.
required:
- cid
- experience
- moe_locale_id
- moe_variation_id
- audience_name
- audience_id
properties:
cid:
type: string
description: Campaign ID. From `experience_context.cid`.
experience:
type: string
description: >-
Experience name. From
`experience_context.experience`.
moe_locale_id:
type: string
description: >-
Locale ID. From
`experience_context.moe_locale_id`.
moe_variation_id:
type: string
description: >-
Variation ID. From
`experience_context.moe_variation_id`.
audience_name:
type: string
description: >-
Audience name. From
`experience_context.audience_name`.
audience_id:
type: string
description: >-
Audience ID. From
`experience_context.audience_id`.
type:
type: string
description: >-
Experience type. From
`experience_context.type`.
enum:
- Web Personalization
b_id:
type: string
description: >
This field can be used to uniquely identify
click tracking events on multiple elements on a
page.
For example, *Add to Cart* & *Wishlist* can be
used to identify if the user has clicked or
tapped on these buttons on the website or the
app.
examples:
Impression Existing User:
summary: Impression (Existing User)
value:
elements:
- customer_id: >-
user_timezone_offset: 19800
actions:
- action: MOE_PERSONALIZATION_MESSAGE_SHOWN
moe_event_uuid: aa886712-4537-47c1-b126-2686efda2e26
event_time: 1725258666
platform: web
attributes:
cid: 66d55ae445921e4d35ae4368_F_T_WP_AB_2_P_0_AU_5A
experience: Test Server side experience
moe_locale_id: '0'
moe_variation_id: '2'
audience_name: All Users
audience_id: 5A
type: Web Personalization
Impression New User:
summary: Impression (New User)
value:
elements:
- customer_id: john@example.com
user_attributes:
name: John Doe
first_name: John
last_name: Doe
user_timezone_offset: 19800
actions:
- action: MOE_PERSONALIZATION_MESSAGE_SHOWN
moe_event_uuid: aa886712-4537-47c1-b126-2686efda2e26
event_time: 1725258666
platform: web
attributes:
cid: 66d55ae445921e4d35ae4368_F_T_WP_AB_2_P_0_AU_5A
experience: Test Server side experience
moe_locale_id: '0'
moe_variation_id: '2'
audience_name: All Users
audience_id: 5A
type: Web Personalization
Impression Anonymous User:
summary: Impression (Anonymous User)
value:
elements:
- customer_id:
user_timezone_offset: 19800
actions:
- action: MOE_PERSONALIZATION_MESSAGE_SHOWN
moe_event_uuid: aa886712-4537-47c1-b126-2686efda2e26
event_time: 1725258666
platform: web
attributes:
cid: 66d55ae445921e4d35ae4368_F_T_WP_AB_2_P_0_AU_5A
experience: Test Server side experience
moe_locale_id: '0'
moe_variation_id: '2'
audience_name: All Users
audience_id: 5A
type: Web Personalization
Click Existing User:
summary: Click (Existing User)
value:
elements:
- customer_id: >-
user_timezone_offset: 19800
actions:
- action: MOE_PERSONALIZATION_MESSAGE_CLICKED
moe_event_uuid: aa886712-4537-47c1-b126-2686efda2e26
event_time: 1725258666
platform: web
attributes:
cid: 66d55ae445921e4d35ae4368_F_T_WP_AB_2_P_0_AU_5A
experience: Test Server side experience
moe_locale_id: '0'
moe_variation_id: '2'
b_id: Add to Cart
audience_name: All Users
audience_id: 5A
type: Web Personalization
Click New User:
summary: Click (New User)
value:
elements:
- customer_id: john@example.com
user_attributes:
name: John Doe
first_name: John
last_name: Doe
user_timezone_offset: 19800
actions:
- action: MOE_PERSONALIZATION_MESSAGE_CLICKED
moe_event_uuid: bb997812-4537-47c1-b126-2686efda2e27
event_time: 1725258670
platform: web
attributes:
cid: 66d55ae445921e4d35ae4368_F_T_WP_AB_2_P_0_AU_5A
experience: Test Server side experience
moe_locale_id: '0'
moe_variation_id: '2'
b_id: Add to Cart
audience_name: All Users
audience_id: 5A
type: Web Personalization
Click Anonymous User:
summary: Click (Anonymous User)
value:
elements:
- customer_id:
user_timezone_offset: 19800
actions:
- action: MOE_PERSONALIZATION_MESSAGE_CLICKED
moe_event_uuid: aa886712-4537-47c1-b126-2686efda2e26
event_time: 1725258666
platform: web
attributes:
cid: 66d55ae445921e4d35ae4368_F_T_WP_AB_2_P_0_AU_5A
experience: Test Server side experience
moe_locale_id: '0'
moe_variation_id: '2'
b_id: Add to Cart
audience_name: All Users
audience_id: 5A
type: Web Personalization
responses:
'200':
description: >
**Success**
The event was accepted by the MoEngage ingestion pipeline.
**Note on idempotency**: Events are deduplicated using
`moe_event_uuid`. On retry, reuse the same UUID from the original
attempt — MoEngage will not double-count it. For a new event, always
generate a fresh UUID.
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: Acknowledgement status, for example `success`.
message:
type: string
description: Human-readable acknowledgement message.
req_id:
type: string
description: >-
Server-assigned request identifier. Include this when
contacting support about a specific call.
example:
status: success
message: Your request has been accepted and will be processed soon.
req_id: SKuSLFnX
'400':
description: >
**Bad Request**
Returned when the payload is malformed JSON, fails validation (for
example, an unsupported `action` or `platform`, a missing required
`attributes` field, or `user_timezone_offset` outside
`-54000`–`54000`), or the `MOE-APPKEY` header is missing or not
recognized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
title: Invalid Field Value
description: >-
elements - Validators Failed : Validator: Element, Errored
Field: actions
code: NwRqMltB
'401':
description: >
**Authorization Failed**
This response is returned when the authorization fails due to
incorrect values for the Workspace ID or Personalize API Key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
title: Authentication required
description: Invalid API_KEY used in Authentication Header
'500':
description: >
**Internal Server Error**
This response is returned when the system runs into an unexpected
error. Retry using the same `moe_event_uuid` from the original
attempt — the event will be safely deduplicated. If the error
persists for more than 5 minutes, contact MoEngage support.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
ErrorResponse:
type: object
description: >-
Standard error envelope returned by Personalize endpoints for `4xx` and
`5xx` responses.
properties:
title:
type: string
description: >-
Short error category, for example `Invalid Field Value`,
`Authentication required`, or `Malformed JSON`.
description:
type: string
description: Human-readable detail describing what failed.
code:
type: string
description: >-
Opaque server-assigned error code. Present on validation failures;
useful when contacting support.
required:
- title
- description
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >
Authentication is done via Basic Auth. This requires a base64-encoded
string of your credentials in the format 'username:password'.
- **Username**: Use your MoEngage workspace ID (also known as the App
ID). You can find it in the MoEngage dashboard at **Settings** >
**Account** > **APIs** > **Workspace ID (earlier app id)**.
- **Password**: Use your API Key, which you can find within the
**Personalize** tile.
**Note**: After you generate and save the Personalize API Key (SECRET
KEY), DO NOT generate a new key unless there is a security breach. After
you generate a different key and save it, API calls using the older key
won't work.
For more information on authentication and getting your credentials,
refer
[here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).
````