> ## 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. # 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. ## OpenAPI ````yaml /api/personalize-experience/personalize-experience.yaml post /experiences/fetch 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/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 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' 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). ````