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: []

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

tags:
  - name: Experiences
    description: API endpoints for fetching experiences and metadata.
  - name: Events
    description: API endpoints for reporting impressions and clicks.

paths:
  /experiences/fetch:
    post:
      tags:
        - Experiences
      summary: Fetch Experience
      description: |
        This API receives data on active personalization experiences. You can fetch data for one or more server-side experiences by using the **experience_key** field. MoEngage will evaluate targeting rules and in-session attributes automatically and return the correct variation for the user. Typically, you would make this call as part of your larger page and content rendering pipeline.

      operationId: fetchExperience
      x-mint:
        content: |
          #### Rate Limit

          The rate limit is **10,000 RPM** (requests per minute), applicable at the workspace (App) level. This limit is configurable on request and may incur additional cost.
      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
              description: |
                To target users on contextual signals such as UTM parameters, referrer, or any custom in-session attribute configured for your workspace, pass the parameter as a top-level field in the request body using the parameter's own name as the key.

                For example, if you have configured an in-session attribute with the query parameter name `utm_medium` and want to target users who arrived from an email campaign:

                ```json
                {
                  "identifiers": { "customer_id": "user_8821" },
                  "experience_key": ["email-landing-banner"],
                  "utm_medium": "email"
                }
                ```

                You can pass any number of these custom keys alongside the documented fields below.
              additionalProperties: true
              example:
                identifiers:
                  customer_id: "user_8821"
                experience_key: ["email-landing-banner"]
                utm_medium: "email"
              properties:
                identifiers:
                  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 fetching experiences that are configured for audiences segmented based on user attributes/user behavior/user affinity/custom segments.
                        
                        If the the **customer_id** is not part of the request **OR** is inaccurate **OR** is not present in MoEngage, **user_identifiers** to uniquely identify the user.
                        
                        It is mandatory to have [Identity Resolution](/user-guide/data/user-data/unified-identity-identity-resolution) implemented for your workspace to use *user_identifiers* as a fallback to **customer_id** for identifying the user.
                    user_identifiers:
                      type: string
                      description: |
                        If you have [Identity Resolution](/user-guide/data/user-data/unified-identity-identity-resolution) enabled for your account, you can use different attributes such as customer ID OR email ID OR mobile number to uniquely identify a user.
                        
                        Apart from email id or phone number, you can use any custom user attribute that is being used as part of the Identity Resolution.
                        
                        If the **user_identifiers** is not part of the request **OR** the **user_identifier** is not present in MoEngage, the API will return experiences configured for All users.
                experience_key:
                  type: array
                  items:
                    type: string
                  maxItems: 25
                  description: |
                    This field uniquely identifies each server-side experience created using MoEngage Personalize. You can pass multiple values in a single request and receive the personalized content defined for each experience in the response.
                    
                    To fetch the payload for a single experience:
                    `experience_key: ["experience-1"]`
                    
                    To fetch payload for multiple experiences in a single call:
                    `experience_key: ["experience-1", "experience-2"]`
                    
                    **Limit**: A maximum of 25 experience keys can be passed per request. If more than 25 are provided, the API returns the first 25 experiences.
                    
                    If no experience_key is specified, API will return:
                    * all experiences for the specified customer_id **OR**
                    * all experiences configured for **all users** if customer_id is not part of the request

                    **Note**: Keys must be obtained from the [Fetch Experience Metadata](#operation/getMetadata) endpoint. An unrecognized key, or a key that the user does not match, returns a `200` response with an empty `experiences` object — not an error.
                DAY_OF_THE_WEEK:
                  type: string
                  description: |
                    This field must contain the day of the week for evaluating IN-session attribute-based experiences.
                    
                    **Accepted values**: `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday` (case-sensitive).
                    
                    Example: `DAY_OF_THE_WEEK: "Sunday"`
                  enum:
                    - Monday
                    - Tuesday
                    - Wednesday
                    - Thursday
                    - Friday
                    - Saturday
                    - Sunday
                TIME_OF_THE_DAY:
                  type: string
                  description: |
                    This field must contain the current hour in 24-hour format (UTC) for evaluating IN-session attribute-based experiences. Pass as a zero-padded two-digit string (`"00"`–`"23"`).
                    
                    **Examples**: midnight = `"00"`, 7 AM = `"07"`, 2 PM = `"14"`, 7 PM = `"19"`, 11 PM = `"23"`.
                  enum: ["00","01","02","03","04","05","06","07","08","09","10","11","12","13","14","15","16","17","18","19","20","21","22","23"]
                USER_IP_ADDRESS:
                  type: string
                  description: This field must contain the user’s IP address to fetch experiences for audiences segmented basis  geo-location.
                USER_AGENT:
                  type: string
                  description: |
                    This field must contain the USER-AGENT HTTP header.
                    This is useful to delivering experiences personalized based on in-session attributes like Device Type.
            examples:
              Single Experience:
                summary: Fetch a single experience
                value:
                  identifiers:
                    customer_id: "user_8821"
                    user_identifiers:
                      u_em: "jane@example.com"
                      u_mb: "+919876543210"
                  experience_key: ["homepage-banner"]
                  DAY_OF_THE_WEEK: "Monday"
                  TIME_OF_THE_DAY: "14"
                  USER_IP_ADDRESS: "203.0.113.42"
                  USER_AGENT: "Mozilla/5.0 (Linux; Android 13) AppleWebKit/537.36"
              Multiple Experiences:
                summary: Fetch multiple experiences in one call
                value:
                  identifiers:
                    customer_id: "user_8821"
                  experience_key: ["homepage-banner", "promo-strip", "cart-upsell"]
              Contextual Targeting (UTM):
                summary: Contextual targeting with UTM medium In-session query parameter
                value:
                  identifiers:
                    customer_id: "user_8821"
                  experience_key: ["email-landing-banner"]
                  utm_medium: "email"
      responses:
        '200':
          description: |
            **Success**
            This response is returned when the request is submitted to MoEngage.
            
            **Note**: A `200` response with an empty `experiences` object (`{}`) means the identified user did not match any audience for the requested experience(s). This is not an error — render your default or fallback UI in this case.
          content:
            application/json:
              schema:
                type: object
                properties:
                  experiences:
                    type: object
                    description: |
                      Map of `experience_key → experience_object`. Returns an empty object `{}` when no experiences match the user.
                    additionalProperties:
                      type: object
                      properties:
                        payload:
                          type: object
                          description: Contains all key-value pairs defined as part of the experience. Variable names are set by the campaign creator in the MoEngage dashboard.
                          additionalProperties:
                            type: object
                            properties:
                              value:
                                description: The content value for this variable. Type depends on `data_type` — a string for `string`, a nested JSON object for `json`.
                                oneOf:
                                  - type: string
                                  - type: object
                              data_type:
                                type: string
                                description: Data type of the value.
                                enum:
                                  - string
                                  - number
                                  - boolean
                                  - json
                                  - float
                        experience_context:
                          type: object
                          description: |
                            Campaign metadata for this experience. **Store this entire object** — its fields must be passed as `attributes` in the [Track Experience Events](#operation/reportExperienceEvents) request to record impressions and clicks.
                          properties:
                            cid:
                              type: string
                              description: Campaign ID. Pass this as `attributes.cid` in Track Experience Events.
                            experience:
                              type: string
                              description: Human-readable experience name from the MoEngage dashboard.
                            moe_locale_id:
                              type: string
                              description: Internal locale identifier. Pass as-is to Track Experience Events.
                            moe_variation_id:
                              type: string
                              description: Variation ID of the A/B variant served to this user. Pass as-is to Track Experience Events.
                            audience_name:
                              type: string
                              description: Name of the audience segment this user matched.
                            audience_id:
                              type: string
                              description: Alphanumeric audience segment ID.
                            type:
                              type: string
                              description: Experience type.
                              enum:
                                - Web Personalization
                            experience_type:
                              type: string
                              description: Internal experience type label (for example, `API based Experience`).
              examples:
                Matched Experience:
                  summary: User matched an experience
                  value:
                    experiences:
                      homepage-banner:
                        payload:
                          Title:
                            value: "Free shipping on orders over ₹999"
                            data_type: string
                          ImageURL:
                            value: "https://cdn.example.com/banners/free-shipping.jpg"
                            data_type: string
                          CtaLabel:
                            value: "Shop Now"
                            data_type: string
                        experience_context:
                          cid: "65eae5738ea5032b0ef60138_F_T_WP_AB_2_P_0_AU_42D"
                          experience: "Homepage Banner — Free Shipping"
                          moe_locale_id: "0"
                          moe_variation_id: "2"
                          audience_name: "High Intent Users"
                          audience_id: "42D"
                          type: "Web Personalization"
                          experience_type: "API based Experience"
                No Match:
                  summary: User did not match any audience — render fallback UI
                  value:
                    experiences: {}
        '400':
          description: |
            **Bad Request**
            Returned when the payload is empty, malformed JSON, contains an invalid field value (for example, an unsupported `DAY_OF_THE_WEEK`), or the `MOE-APPKEY` header is missing or not recognized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Invalid Field Value:
                  summary: A request field has an unsupported value
                  value:
                    title: "Invalid Field Value"
                    description: "DAY_OF_THE_WEEK - Enum doesnt allow value: funday, allowed values: [Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday]"
                    code: "GvHogFKc"
                Malformed JSON:
                  summary: Request body is not valid UTF-8 JSON
                  value:
                    title: "Malformed JSON"
                    description: "Could not decode the request body. The JSON was incorrect or not encoded as UTF-8."
                Invalid Workspace:
                  summary: MOE-APPKEY header is missing or unknown
                  value:
                    title: "Request Error"
                    description: "MoEngage Client not found. Please check values for headers - MOE-APPKEY or MOE-DBNAME"
        '401':
          description: |
            **Authorization Failed**
            This response is returned when the authorization fails due to incorrect values for the Workspace ID or Personalize API Key.
            
            **Common causes**:
            - Using the general API Key instead of the Personalize-specific Secret Key found in Settings > API Keys > Personalize.
            - The Personalize API Key was regenerated — all calls using the old key immediately return `401`.
            - The `Authorization` header Base64 value was not encoded correctly.
          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 with exponential backoff. If the error persists for more than 5 minutes, contact MoEngage support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /experiences/metadata:
    get:
      tags:
        - Experiences
      summary: Fetch Experience Metadata
      description: |
        This API fetches a list of currently Active, Scheduled, and Paused experiences within a workspace.
      x-mint:
        content: |
          <Tip>
            **Recommended usage**: Call this endpoint once at application startup and cache the result. Experience keys change infrequently — a daily refresh is usually sufficient. In production rendering paths, filter by `?status=Active` so your [Fetch Experience](/api/experiences/fetch-experience) calls only include keys that are currently live.
          </Tip>

      operationId: getMetadata
      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"
        - name: status
          in: query
          required: false
          description: |
            Filter experiences by status. Pass one or more comma-separated values. If omitted, all statuses are returned.
            
            **Accepted values**: `Active`, `Paused`, `Scheduled` (case-sensitive). Unknown values (for example, `active` in lowercase) silently return an empty list rather than an error — verify spelling and casing.

            | Status | Description |
            |---|---|
            | `Active` | Experience is live and being served to matching users. |
            | `Paused` | Experience is not being served. Fetching its key via [Fetch Experience](/api/experiences/fetch-experience) returns an empty payload — not an error. |
            | `Scheduled` | Experience is configured but has not started yet. Fetching its key returns an empty payload. |
          schema:
            type: string
            example: "Active,Paused"
      x-codeSamples:
        - lang: cURL
          label: Fetch all experiences
          source: |
            curl --location 'https://sdk-01.moengage.com/v1/experiences/metadata' \
            --header 'Accept: */*' \
            --header 'Content-Type: application/json' \
            --header 'Authorization: Basic <base64(workspaceId:personalizeApiKey)>' \
            --header 'MOE-APPKEY: <Your Workspace ID>'
        - lang: cURL
          label: Fetch by Status (Active)
          source: |
            curl --location 'https://sdk-01.moengage.com/v1/experiences/metadata?status=Active' \
            --header 'Accept: */*' \
            --header 'Content-Type: application/json' \
            --header 'Authorization: Basic <base64(workspaceId:personalizeApiKey)>' \
            --header 'MOE-APPKEY: <Your Workspace ID>'
        - lang: cURL
          label: Fetch by Status (Active,Paused)
          source: |
            curl --location 'https://sdk-01.moengage.com/v1/experiences/metadata?status=Active,Paused' \
            --header 'Accept: */*' \
            --header 'Content-Type: application/json' \
            --header 'Authorization: Basic <base64(workspaceId:personalizeApiKey)>' \
            --header 'MOE-APPKEY: <Your Workspace ID>'
      responses:
        '200':
          description: Successful retrieval
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    type: object
                    properties:
                      count:
                        type: integer
                        description: Total number of experiences returned after the status filter is applied.
                      experiences:
                        type: array
                        items:
                          type: object
                          properties:
                            experience_name:
                              type: string
                              description: Human-readable name set in the MoEngage dashboard.
                            experience_key:
                              type: string
                              description: Unique key for this experience. Pass this value in the `experience_key` array of the [Fetch Experience](/api/experiences/fetch-experience) request.
                            status:
                              type: string
                              description: Current status of the experience.
                              enum:
                                - Active
                                - Paused
                                - Scheduled
              examples:
                All statuses:
                  summary: Multiple experiences, mixed statuses
                  value:
                    metadata:
                      count: 3
                      experiences:
                        - experience_name: "Homepage Banner — Free Shipping"
                          experience_key: "homepage-banner"
                          status: Active
                        - experience_name: "Cart Upsell Widget"
                          experience_key: "cart-upsell"
                          status: Paused
                        - experience_name: "Christmas Sale Strip"
                          experience_key: "christmas-sale-strip"
                          status: Scheduled
                Active only:
                  summary: Active filter applied
                  value:
                    metadata:
                      count: 1
                      experiences:
                        - experience_name: "Homepage Banner — Free Shipping"
                          experience_key: "homepage-banner"
                          status: Active
                No experiences:
                  summary: No experiences match the filter
                  value:
                    metadata:
                      count: 0
                      experiences: []
        '400':
          description: |
            **Bad Request**
            This response is returned when the `MOE-APPKEY` header is missing or not recognized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                title: "Request Error"
                description: "MoEngage Client not found. Please check values for headers - MOE-APPKEY or MOE-DBNAME"
        '401':
          description: |
            **Authorization Failed**
            This response is returned when the authorization fails due to incorrect values for the Workspace ID or Personalize API Key. Refer to the authentication guidance in the `basicAuth` security scheme above.
          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 after a short delay. If the error persists, contact MoEngage support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /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.
      x-mint:
        content: |
          <Warning>
            If you do not call this endpoint, your MoEngage analytics dashboard will show zero impressions and zero clicks, and campaign reporting will be empty.
          </Warning>
      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: "<unique user identifier like email or phone number. Eg: john@example.com>"
                      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: "<identifier for the user for the session>"
                      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: "<unique user identifier like email or phone number. Eg: john@example.com>"
                      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: "<identifier for the user for the session>"
                      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'