Fetch Experience

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.

POST /experiences/fetch

cURL

Single Experience

curl --request POST \
  --url https://sdk-{dc}.moengage.com/v1/experiences/fetch \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'MOE-APPKEY: <moe-appkey>' \
  --data '
{
  "identifiers": {
    "customer_id": "user_8821",
    "user_identifiers": {
      "u_em": "[e-mail]",
      "u_mb": "[phone]"
    }
  },
  "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"
}
'

200

Matched Experience

{
  "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"
      }
    }
  }
}

Authorizations

Authorization · string · header · required

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.

Headers

MOE-APPKEY · string · required

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

Example:

"Workspace ID"

Body

application/json

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:

{
  "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.

identifiers · object

Show child attributes

experience_key · string[]

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

Maximum array length: 25

DAY_OF_THE_WEEK · enum<string>

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"

Available options: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday

TIME_OF_THE_DAY · enum<string>

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

Available options: 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 · string

This field must contain the user’s IP address to fetch experiences for audiences segmented basis geo-location.

USER_AGENT · string

This field must contain the USER-AGENT HTTP header. This is useful to delivering experiences personalized based on in-session attributes like Device Type.

Response

200

application/json

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.

experiences · object

Map of experience_key → experience_object. Returns an empty object {} when no experiences match the user.

Show child attributes