> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/_mcp/server.

## Endpoints

[Create a profile](/references/experience-api/profiles/create-a-profile)

[Get a profile](/references/experience-api/profiles/get-a-profile)

[Update a profile](/references/experience-api/profiles/update-a-profile)

[Delete a profile](/references/experience-api/profiles/delete-a-profile)

[Batch upsert profiles (sync)](/references/experience-api/profiles/create-or-update-profiles-sync)

You can use this endpoint to push data from your own existing customer data systems into Contentful Personalization profiles in real-time, in periodic batches, or in bulk, as part of a first-time migration.

This endpoint upserts profiles, meaning that when events are passed for profile IDs that do not yet exist, profiles at those IDs will be created. This ensures that you do not have to check whether profiles at specific IDs exist prior to migration.

> **Info**
>
> **NOTE:** This endpoint is intended to be used server-side. Because of that, it does not accept options related to resolving location or IP address. You may, however, still specify location data on events.

This endpoint accepts up to 200 events, with a maximum of 50 `identify` events, across a maximum of 50 unique profiles.

> **Info**
>
> **NOTE:**
> Unlike the single-profile endpoints (Create, Update, Get), the batch endpoint returns **profiles only** — it does not return `experiences` or `changes`. If you need variant selections, use the single-profile endpoints instead.

[Batch upsert profiles (async)](/references/experience-api/profiles/create-or-update-profiles-async)

This endpoint accepts the same request body as [Batch upsert profiles (sync)](/references/experience-api/profiles/create-or-update-profiles-sync) but processes events asynchronously. It returns immediately with a confirmation message and processes events in the background.

This is a fire-and-forget endpoint suited for server-side integrations that do not need to render personalized content in the response.

> **Info**
>
> **Note:** Because processing is deferred, this endpoint returns `200` even if the organization or environment does not exist. Errors are handled internally during background processing.

> **Info**
>
> **Important:** The organization ID (or API key) is the Client ID field value displayed under the "SDK Keys" section, on the Optimization tab.
>
> ![Client ID](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/contentful.docs.buildwithfern.com/d9c1e92409fed1e1c97c28fd1fc9f7c5e1fcfcdc19c22cc05eba86b166a94a5f/docs/assets/images/client-id.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260929%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260929T232250Z&X-Amz-Expires=604800&X-Amz-Signature=1ca80f23a00440ead55c19419b69dd1d1661861808b7479ae8d858ed62c4c298&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## FAQ

**What happens to any aliases that a profile uses?**

* In case the profile is being aliased, the original profile is removed. As such, all aliases will also return `404`.

**Can I batch-delete profiles?**

* No, you cannot batch-delete profiles because the batch endpoints only work for events. You have to make one request per the profile that should be deleted. There is no limit on the number of requests you can send at a time.

## Tips

* We highly recommend that you use the `profileID` that is returned by the Contentful Personalization profile once you have identified the user. Retrieving and updating profiles with this returned ID is more performant than using an ID you have supplied when creating or aliasing a profile.
* The payload you supply to these endpoints can be sent with the `content-type` header set as either `application/json` or `text/plain`. We recommend that you use `text/plain` whenever possible to minimize request roundtrip time by [avoiding triggering a CORS preflight request](https://developer.mozilla.org/en-US/docs/Glossary/CORS-safelisted_request_header). Our SDKs automatically send requests as `text/plain`.
* If you want to ensure that a user's location is not resolved as part of a create profile or update profile endpoint request, you can either:
  1. Set an empty string or object, whichever is applicable, to each `context.location` argument, OR
  2. Not set `location` or supply `location: undefined` or `location: {}` , do not supply `location` as an option, and set `context.library.version` to a string that represents a semver of `3.14` or greater.

## Types

### Response

The returned response of each API endpoint is a data structure indicating the complete representation of the profile(s) and the Experiences & variants that the Experience API has selected for the profile(s). The single-profile endpoints (`Create`, `Update`, and `Get`) return a single profile with experience variant selections and changes. The `Batch upsert` endpoint returns an array of profiles without variant selections or changes.

```typescript
/**
 * Single-profile endpoints return this shape inside the response envelope's `data` field.
 */
type ProfileWithSelectedVariants = {
    profile: Profile;
    experiences: SelectedVariantInfo[];
    changes: Change[];
};
```

### Profile

A profile is a holistic representation of a single user. The Contentful Personalization Experience API computes and returns a visitor's `profile` in response to `page`, `track`, `identify`, `screen`, and `component` events. The profile is also used within Experience SDKs to determine the appropriate experience variants and Merge Tag values to render.

```typescript
type Profile = {
    id: string;
    stableId: string;
    random: number; // Legacy field, not used for variant selection
    audiences: string[];
    traits: Record<string, any>; // Any valid JSON
    location: {
        coordinates?: {
            latitude: number;
            longitude: number;
        } | undefined;
        city?: string | undefined;
        postalCode?: string | undefined;
        region?: string | undefined;
        regionCode?: string | undefined;
        country?: string | undefined;
        countryCode?: string | undefined;
        continent?: string | undefined;
        timezone?: string | undefined;
    };
    session: {
        id?: string;
        isReturningVisitor: boolean;
        landingPage: {
            path: string;
            url: string;
            query: Record<string, string>;
            referrer: string;
            search: string;
        };
        count: number;
        activeSessionLength: number;
        averageSessionLength: number;
    };
    jurisdiction?: 'US' | 'EU';
    stickyVariants?: Record<string, number>; // Maps experienceId to variantIndex
}
```

### Experience

Each response from the Experience API also returns an array of experiences assigned to the profile. You may see this typed in the SDKs as `SelectedVariantInfo`. Experiences must be published in the content source to be returned on the Experience API. Each experience indicates the variant index (0 = control, 1 = variant 1, etc.) and the content source IDs of content to show.

```typescript
type Experience = {
    experienceId: string;
    variantIndex: number;
    variants: Record<string, string>;
    sticky?: boolean;
}

type SelectedVariantInfo = Experience; // The type name used in our SDKs
```

The key of each `variants` Record is the content source's ID of the baseline or control content. The value of each variant Record is the content source's ID of the applicable variant content. When the variant index is 0, the key and value are the same, otherwise they will be different.

When `sticky` is `true`, the variant selection has been locked in for this profile and will not change even if the experience's distribution configuration is modified.

```json
{
    "experiences": [
        { "experienceId": "1", "variantIndex": 0, "variants": {"entryA": "entryA"} },
        { "experienceId": "2", "variantIndex": 1, "variants": {"entryB": "entryC"}, "sticky": true }
    ]
}
```

### Change

The `changes` array contains inline variable personalizations — where a single keyed value is changed rather than an entire CMS entry being replaced. Each change tells the SDK: for this key, use this value.

```typescript
type Change = {
    key: string;            // e.g. "heroTitle", "ctaColor"
    type: 'Variable';       // Currently the only type
    value: string | number | boolean | object;
    meta: {
        experienceId: string;
        variantIndex: number;
    };
}
```

```json
{
    "changes": [
        { "key": "heroTitle", "type": "Variable", "value": "Welcome back!", "meta": { "experienceId": "exp-1", "variantIndex": 1 } },
        { "key": "ctaColor", "type": "Variable", "value": "#ff6600", "meta": { "experienceId": "exp-2", "variantIndex": 2 } }
    ]
}
```

### Event

Each POST endpoint accepts arrays of events as part of requests. Events are the building blocks of profiles; they indicate the actions taken and attributes of individual profiles so those profiles can be segmented into Audiences.

The API accepts five event types: `page`, `track`, `identify`, `screen`, and `component`.

```typescript
type Event = {
  anonymousId: string; // Only when using the batch endpoint, otherwise omitted
  channel: 'web' | 'mobile' | 'server' | 'client'; // 'client' is transformed to 'web'
  context: {
    app?: {  // Optional in API requests
      name: string;
      version: string;
    },
    // Powers `has viewed page` UTM parameter Audience conditions
    campaign?: {
      name: string;
      source: string;
      medium: string;
      term: string;
      content: string;
    },
    // Describes the library making the request
    library: {
      name: string;
      version: string;
    },
    locale?: string; // ISO 639-1 + ISO 3166-2, e.g., "en-US"
    // Optional — the server can resolve location from request headers when the "location" feature is enabled
    location?: {
      coordinates?: {
        latitude: number;
        longitude: number
      },
      city?: string; // Use proper capitalization of the city name
      postalCode?: string;
      region?: string;
      regionCode?: string; // ISO 3166-2
      country?: string;
      countryCode?: string; // ISO 3166-1 alpha-2
      continent?: string;
      timezone?: string;
    },
    // Used for various `has viewed page` Audience conditions
    page?: {
      path: string;
      query: Record<string, string>; // Object of query:value pairs
      referrer: string; // Use full URL including protocol, path, and query string
      search: string; // Full querystring, e.g., "?query=value"
      url: string; // Use full URL including protocol, path, and query string
    }
    userAgent?: string
  }
  messageId: string; // Generate a UUID
  timestamp: Date; // Typically assigned as Date.now()
  type: "page" | "track" | "identify" | "screen" | "component";
  event?: string; // Required when type === "track"
  userId?: string; // Required when type === "identify"
  traits?: Record<string, any>; // Any valid JSON. Required when type === 'identify'
  // Required when type === "page" or type === "track"
  properties?: {
    // The following five properties must be set when type === "page"
    // Not required for events of type === "track"
    path: string;
    query: Record<string, string>; // Object of query:value pairs
    referrer: string; // Use full URL including protocol, path, and query string
    search: string; // Full querystring, e.g., "?query=value"
    url: string; // Use full URL including protocol, path, and query string
    // Any additional properties that can be parsed as valid JSON may be set here
    [key: string]: any;
  }
  // The following fields are only for component view events (type === "component")
  componentId?: string; // Required when type === "component"
  componentType?: 'Entry' | 'Variable';
  experienceId?: string; // Required for sticky variant persistence
  variantIndex?: number; // Required for sticky variant persistence
  viewDurationMs?: number; // Milliseconds
  viewId?: string;
}
```

#### Screen events

Screen events (`type: "screen"`) are the mobile equivalent of page events. They require `properties.name` to be set:

```typescript
// Required properties for screen events
properties: {
  name: string;
  [key: string]: any;
}
```

#### Component view events

Component view events (`type: "component"`) are used primarily to persist sticky variant selections. When both `experienceId` and `variantIndex` are set on a component event, the server stores the mapping so the visitor continues seeing the same variant on subsequent requests.

### Options

The API endpoints also accept options to modify the behaviour of the request. These are available only on the create profile and update profile endpoints (not the batch endpoints).

```typescript
type CreateOrUpdateProfilePayload = {
   events: Event[];
   options?: Options;
}

type Options = {
    location?: GeoLocation;
    features?: Feature[];
}

type Feature = "location" | "ip-enrichment"
```

* Specifying `location` in `options` provides client-side geo-location data that supplements or overrides server-side location resolution.
* Including `"location"` in the `features` array will attempt to resolve the location of the user based on request headers (Cloudflare's location data).
  * If you do not want location to be resolved when sending events, do not add `location` as a feature option and ensure that `context.library.version` is set on any accompanying event as a string representing a semver greater than `3.14`.
* Including `"ip-enrichment"` in the `features` array will attempt to resolve firmographic data with a connected Albacross API Key. See [Albacross](https://www.albacross.com/) for more information.

### Traits

`traits` are arbitrary JSON data set by `identify` events. Traits are shallow merged together; the most recent value of a given trait key overwrites the prior value.

Traits are useful for custom segmentation using `has trait` rules. Additionally, traits can serve as snippets for dynamic inline personalizations.

> Example for an inline Personalization:
>
> `` const headline = `Hey ${profile.traits.firstname}` ``.

```typescript
type Traits = {
  [key: string]: string | number | boolean | Traits;
};

// example
const traits: Traits = {
  "firstname": "Max",
  "address": {
    "street": "Allee 33"
  },
  "company": "Wayne Enterprises, Inc."
}
```


## API Docs

- Profiles [Create a profile](https://contentful.com/developers/docs/references/experience-api/profiles/create-a-profile.md)
- Profiles [Get a profile](https://contentful.com/developers/docs/references/experience-api/profiles/get-a-profile.md)
- Profiles [Update a profile](https://contentful.com/developers/docs/references/experience-api/profiles/update-a-profile.md)
- Profiles [Delete a profile](https://contentful.com/developers/docs/references/experience-api/profiles/delete-a-profile.md)
- Profiles [Create or update profiles (sync)](https://contentful.com/developers/docs/references/experience-api/profiles/create-or-update-profiles-sync.md)
- Profiles [Create or update profiles (async)](https://contentful.com/developers/docs/references/experience-api/profiles/create-or-update-profiles-async.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://contentful.com/developers/docs/openapi.json)
- [OpenAPI YAML](https://contentful.com/developers/docs/openapi.yaml)