Profiles

Endpoints

Create a profile

Get a profile

Update a profile

Delete a profile

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

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

Batch upsert profiles (async)

This endpoint accepts the same request body as Batch upsert 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.

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

1
/**
2
 * Single-profile endpoints return this shape inside the response envelope's `data` field.
3
 */
4
type ProfileWithSelectedVariants = {
5
    profile: Profile;
6
    experiences: SelectedVariantInfo[];
7
    changes: Change[];
8
};

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.

1
type Profile = {
2
    id: string;
3
    stableId: string;
4
    random: number; // Legacy field, not used for variant selection
5
    audiences: string[];
6
    traits: Record<string, any>; // Any valid JSON
7
    location: {
8
        coordinates?: {
9
            latitude: number;
10
            longitude: number;
11
        } | undefined;
12
        city?: string | undefined;
13
        postalCode?: string | undefined;
14
        region?: string | undefined;
15
        regionCode?: string | undefined;
16
        country?: string | undefined;
17
        countryCode?: string | undefined;
18
        continent?: string | undefined;
19
        timezone?: string | undefined;
20
    };
21
    session: {
22
        id?: string;
23
        isReturningVisitor: boolean;
24
        landingPage: {
25
            path: string;
26
            url: string;
27
            query: Record<string, string>;
28
            referrer: string;
29
            search: string;
30
        };
31
        count: number;
32
        activeSessionLength: number;
33
        averageSessionLength: number;
34
    };
35
    jurisdiction?: 'US' | 'EU';
36
    stickyVariants?: Record<string, number>; // Maps experienceId to variantIndex
37
}

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.

1
type Experience = {
2
    experienceId: string;
3
    variantIndex: number;
4
    variants: Record<string, string>;
5
    sticky?: boolean;
6
}
7
8
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.

1
{
2
    "experiences": [
3
        { "experienceId": "1", "variantIndex": 0, "variants": {"entryA": "entryA"} },
4
        { "experienceId": "2", "variantIndex": 1, "variants": {"entryB": "entryC"}, "sticky": true }
5
    ]
6
}

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.

1
type Change = {
2
    key: string;            // e.g. "heroTitle", "ctaColor"
3
    type: 'Variable';       // Currently the only type
4
    value: string | number | boolean | object;
5
    meta: {
6
        experienceId: string;
7
        variantIndex: number;
8
    };
9
}

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

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.

1
type Event = {
2
  anonymousId: string; // Only when using the batch endpoint, otherwise omitted
3
  channel: 'web' | 'mobile' | 'server' | 'client'; // 'client' is transformed to 'web'
4
  context: {
5
    app?: {  // Optional in API requests
6
      name: string;
7
      version: string;
8
    },
9
    // Powers `has viewed page` UTM parameter Audience conditions
10
    campaign?: {
11
      name: string;
12
      source: string;
13
      medium: string;
14
      term: string;
15
      content: string;
16
    },
17
    // Describes the library making the request
18
    library: {
19
      name: string;
20
      version: string;
21
    },
22
    locale?: string; // ISO 639-1 + ISO 3166-2, e.g., "en-US"
23
    // Optional — the server can resolve location from request headers when the "location" feature is enabled
24
    location?: {
25
      coordinates?: {
26
        latitude: number;
27
        longitude: number
28
      },
29
      city?: string; // Use proper capitalization of the city name
30
      postalCode?: string;
31
      region?: string;
32
      regionCode?: string; // ISO 3166-2
33
      country?: string;
34
      countryCode?: string; // ISO 3166-1 alpha-2
35
      continent?: string;
36
      timezone?: string;
37
    },
38
    // Used for various `has viewed page` Audience conditions
39
    page?: {
40
      path: string;
41
      query: Record<string, string>; // Object of query:value pairs
42
      referrer: string; // Use full URL including protocol, path, and query string
43
      search: string; // Full querystring, e.g., "?query=value"
44
      url: string; // Use full URL including protocol, path, and query string
45
    }
46
    userAgent?: string
47
  }
48
  messageId: string; // Generate a UUID
49
  timestamp: Date; // Typically assigned as Date.now()
50
  type: "page" | "track" | "identify" | "screen" | "component";
51
  event?: string; // Required when type === "track"
52
  userId?: string; // Required when type === "identify"
53
  traits?: Record<string, any>; // Any valid JSON. Required when type === 'identify'
54
  // Required when type === "page" or type === "track"
55
  properties?: {
56
    // The following five properties must be set when type === "page"
57
    // Not required for events of type === "track"
58
    path: string;
59
    query: Record<string, string>; // Object of query:value pairs
60
    referrer: string; // Use full URL including protocol, path, and query string
61
    search: string; // Full querystring, e.g., "?query=value"
62
    url: string; // Use full URL including protocol, path, and query string
63
    // Any additional properties that can be parsed as valid JSON may be set here
64
    [key: string]: any;
65
  }
66
  // The following fields are only for component view events (type === "component")
67
  componentId?: string; // Required when type === "component"
68
  componentType?: 'Entry' | 'Variable';
69
  experienceId?: string; // Required for sticky variant persistence
70
  variantIndex?: number; // Required for sticky variant persistence
71
  viewDurationMs?: number; // Milliseconds
72
  viewId?: string;
73
}

Screen events

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

1
// Required properties for screen events
2
properties: {
3
  name: string;
4
  [key: string]: any;
5
}

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

1
type CreateOrUpdateProfilePayload = {
2
   events: Event[];
3
   options?: Options;
4
}
5
6
type Options = {
7
    location?: GeoLocation;
8
    features?: Feature[];
9
}
10
11
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 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}`.

1
type Traits = {
2
  [key: string]: string | number | boolean | Traits;
3
};
4
5
// example
6
const traits: Traits = {
7
  "firstname": "Max",
8
  "address": {
9
    "street": "Allee 33"
10
  },
11
  "company": "Wayne Enterprises, Inc."
12
}