Personalize Management API

The Create an Attribute request lets you create a new attribute in a project.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

The Get all Attributes request fetches the list of all the attributes in a project.

To configure the permissions for your application via OAuth, include the personalize:read or personalize:manage scope.

The Update an Attribute request lets you update an existing attribute in a project.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

The Delete an Attribute request lets you delete an existing attribute in a project.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

The Create an Audience request lets you create a new audience in a project.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

The examples below provide a detailed explanation on creating audiences with various parameters.

Create audience with Custom Attributes:

{
  "name": "Valuable US Visitors",
  "description": "US Visitors with an average order value greater than $1000",
  "definition": {
    "__type": "RuleCombination",
    "combinationType": "AND",
    "rules": [
      {
        "__type": "Rule",
        "attribute": {
          "__type": "PresetAttributeReference",
          "ref": "COUNTRY"
        },
        "attributeMatchCondition": "STRING_EQUALS",
        "attributeMatchOptions": {
          "__type": "StringMatchOptions",
          "value": "US"
        },
        "invertCondition": false
      },
      {
        "__type": "Rule",
        "attribute": {
          "__type": "CustomAttributeReference",
          "ref": "66702e03d84509d0106bec05"
        },
        "attributeMatchOptions": {
          "__type": "NumberMatchOptions",
          "value": 1000
        },
        "attributeMatchCondition": "NUMBER_GREATER_THAN",
        "invertCondition": false
      }
    ]
  }
}

This example creates an audience with Custom Attributes. We have two rules being matched here, the second one matching a custom attribute. The __type on the attribute allows you to specify whether the attribute is Custom or Preset.

Match Query Parameters:

{
  "name": "Black Friday Campaign",
  "description": "Visitors targeted with the Black Friday Campaign",
  "definition": {
    "__type": "RuleCombination",
    "combinationType": "AND",
    "rules": [
      {
        "__type": "Rule",
        "attribute": {
          "__type": "PresetAttributeReference",
          "ref": "QUERY_PARAMETERS"
        },
        "attributeMatchCondition": "JSON_MATCH",
        "attributeMatchOptions": {
          "__type": "JSONMatchOptions",
          "pointer": "/utm_campaign",
          "matchCondition": "STRING_EQUALS",
          "matchOptions": {
            "__type": "StringMatchOptions",
            "value": "BLACK_FRIDAY"
          },
          "invertCondition": false
        },
        "invertCondition": false
      }
    ]
  }
}

Query Parameters are a Preset Attribute. In this example, the query parameter utm_campaign is matched for a BLACK_FRIDAY value. The JSONMatchOptions type allow you to nest a matchOptions so that you can match specific values for the parameter.

Match Date and Time:

{
  "name": "Black Friday Campaign",
  "description": "Visitors targeted with the Black Friday Campaign",
  "definition": {
    "__type": "RuleCombination",
    "combinationType": "AND",
    "rules": [
      {
        "__type": "Rule",
        "attribute": {
          "__type": "PresetAttributeReference",
          "ref": "QUERY_PARAMETERS"
        },
        "attributeMatchOptions": {
          "__type": "JSONMatchOptions",
          "pointer": "/utm_campaign",
          "matchCondition": "STRING_EQUALS",
          "matchOptions": {
            "__type": "StringMatchOptions",
            "value": "BLACK_FRIDAY"
          },
          "invertCondition": false
        },
        "attributeMatchCondition": "JSON_MATCH",
        "invertCondition": false
      },
      {
        "__type": "Rule",
        "attribute": {
          "__type": "PresetAttributeReference",
          "ref": "DATE_AND_TIME"
        },
        "attributeMatchCondition": "BETWEEN_TIME",
        "attributeMatchOptions": {
          "__type": "DateTimeMatchOptions",
          "startTime": "2024-11-29T00:00:00",
          "endTime": "2024-11-29T23:59:59",
          "useVisitorTimezone": true
        },
        "invertCondition": false
      }
    ]
  }
}

Date and Time is a Preset Attribute. In this example, we extend the Black Friday Campaign audience to also match only on the day of Black Friday. useVisitorTimezone allows us to evaluate the conditions in the visitors timezone.

The Get all Audiences request fetches the list of all the audiences in a project.

To configure the permissions for your application via OAuth, include the personalize:read or personalize:manage scope.

The Update an Audience request lets you update an existing audience in a project.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

For more detailed request body documentation, please refer to the Create an Audience request.

The Delete an Audience request lets you delete an existing audience in a project.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

The Create an Experience request lets you create a new experience in a project. An experience can be either of SEGMENTED or AB_TEST type. Creating an experience also creates an empty draft version for the configuration.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

Create a Segmented Experience:

{
  "name": "Australian Users Experience",
  "description": "This is the experience for Australian users.",
  "__type": "SEGMENTED"
}

In this example, we create a Segmented Experience. The __type field is used to set the type of the experience. Note that the experience in the response has a latestVersion field pointing to the draft version configuration created along with the experience.

The Get all Experiences request fetches the list of all the experiences in a project.

To configure the permissions for your application via OAuth, include the personalize:read or personalize:manage scope.

The Update an Experience request lets you update an existing experience in a project. Note that once an experience of a particular type has been created, the type cannot be changed with this request.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

The Get a Single Experience request fetches a specific experience created in your project.

To configure the permissions for your application via OAuth, include the personalize:read scope.

The Delete an Experience request lets you delete an existing experience in a project.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

The Create an Experience Version request lets you create a new version of an experience in a project.

Creating a new version allows you to modify the configuration of an existing active version. A version can be created with a DRAFT or ACTIVE status. A new version cannot be created if a DRAFT version already exists, in which case you can only modify the existing DRAFT version.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

Create a Segmented Experience version:

{
  "status": "DRAFT",
  "variants": [
    {
      "__type": "SegmentedVariant",
      "name": "Australian Continent Visitors",
      "shortUid": "0",
      "audiences": [
        "388888800000000087654321",
        "399999900000000044444444"
      ],
      "audienceCombinationType": "OR"
    }
  ]
}

In this example, we create a new DRAFT version of our segmented experience. We want to target the entire Australian continent instead of just the country, and accordingly, we also target one more audience in the variant and change the audienceCombinationType. The short UID refers to the existing variant's short UID so that we can update it.

Create an active version:

{
  "status": "ACTIVE",
  "variants": [
    {
      "__type": "ABTestVariant",
      "name": "Control",
      "shortUid": "0",
      "trafficDistribution": 33.33
    },
    {
      "__type": "ABTestVariant",
      "name": "Purple",
      "shortUid": "1",
      "trafficDistribution": 33.33
    },
    {
      "__type": "ABTestVariant",
      "name": "Red",
      "trafficDistribution": 33.33
    }
  ],
  "variantSplit": "EQUALLY_SPLIT",
  "metrics": [
    {
      "__type": "Primary",
      "event": "244444400000000087654321",
      "name": "Click on CTA"
    }
  ],
  "targeting": {
    "audience": {
      "audiences": [
        "155555500000000012345678"
      ],
      "audienceCombinationType": "AND"
    }
  }
}

The example here is the same A/B test, however, instead of creating a DRAFT version, we're activating the version instantly. The changes in the version are instantly reflected and the existing version is ARCHIVED.

The Get all Experience Versions request fetches the list of all the versions for a given Experience.

The list of versions is sorted by the createdAt date.

To configure the permissions for your application via OAuth, include the personalize:read or personalize:manage scope.

The Update an Experience Version request lets you update an existing version of an Experience. After creating an Experience initially, an empty draft version is already created, and you can update it to modify the configuration of the Experience. Once the configuration is ready, you can activate the version by updating the status to ACTIVE. Any existing active version's status will change to ARCHIVED. You can also PAUSE an active version with this request.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

Update a Segmented Experience version:

{
  "status": "DRAFT",
  "variants": [
    {
      "__type": "SegmentedVariant",
      "name": "Australian Visitors",
      "audiences": [
        "388888800000000087654321"
      ],
      "audienceCombinationType": "AND"
    }
  ]
}

In this example, we update the configuration for the Segmented Experience created previously. We're creating a variant for the visitors from Australia, with the variant targeted to the Australian audience. Notice that the shortUid is skipped for the new variant as it will be generated on the server side.

Activate a version:

{
  "status": "ACTIVE",
  "variants": [
    {
      "__type": "ABTestVariant",
      "name": "Control",
      "trafficDistribution": 50
    },
    {
      "__type": "ABTestVariant",
      "name": "Purple",
      "trafficDistribution": 50
    }
  ],
  "variantSplit": "EQUALLY_SPLIT",
  "metrics": [
    {
      "__type": "Primary",
      "event": "244444400000000087654321",
      "name": "Click on CTA"
    }
  ]
}

Activating a version is done by updating the status to ACTIVE. Any existing active version will be ARCHIVED following the activation of a new version.

Pause a version:

{
  "status": "PAUSED",
  "variants": [
    {
      "__type": "ABTestVariant",
      "name": "Control",
      "trafficDistribution": 50
    },
    {
      "__type": "ABTestVariant",
      "name": "Purple",
      "trafficDistribution": 50
    }
  ],
  "variantSplit": "EQUALLY_SPLIT",
  "metrics": [
    {
      "__type": "Primary",
      "event": "244444400000000087654321",
      "name": "Click on CTA"
    }
  ]
}

Pausing a version is achieved by updating the status to PAUSED. Once paused, the experience does not match any variants and will return null in the Manifest API. You can also re-activate the version again by updating it with the ACTIVE status.

The Delete an Experience Version request lets you discard the draft version of an Experience. Attempting to delete an ACTIVE, PAUSED or ARCHIVED version will return an error.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

The Create an Event request lets you create a new event in a project.

The key field is used to uniquely identify the event. You'll use it when triggering an event from the API or SDK.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

The Get all Events request fetches the list of all the events in a project.

To configure the permissions for your application via OAuth, include the personalize:read or personalize:manage scope.

The Update an Event request lets you update an existing event in a project.

The key field is used to uniquely identify the event. You'll use it when triggering an event from the API or SDK.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

The Delete an Event request lets you delete an existing event in a project.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

The Get Experiences Priority request retrieves the experience priority order for a given project. This contains every experience available within the project sorted in decreasing order of priority.

To configure the permissions for your application via OAuth, include the personalize:read or personalize:manage scope.

The Update Experiences Priority request lets you rearrange experiences in the priority order at any given time. For example, if you create a new experience that should have a higher priority than others, the priority order can be updated after creating the new experience.

To configure the permissions for your application via OAuth, include the personalize:manage scope.

The Get Analytics Summary request fetches the analytics summary of a specific experience of a project. The summary gives you a count of impressions and conversions for a variant, along with its probability to be best in the given timeframe. The leading or winning variant information as determined by the analytics engine is also calculated and returned provided that sufficient data exists.

Please note that leading variant and conversion information is only available on A/B test experiences.

To configure the permissions for your application via OAuth, include the personalize:read or the personalize:manage scope.

The Get Time-series Analytics request fetches the time-series analytics of a specific experience of a project. The response contains hourly impressions and conversions for the specified time-frame. The duration for each interval is specified in the ISO-8601 interval format.

To configure the permissions for your application via OAuth, include the personalize:read or personalize:manage scope.

The Get all Regions request fetches all the region-based information based on the provided search query. Regions are administrative divisions of a country, such as states or provinces, defined according to ISO 3166-2 (https://en.wikipedia.org/wiki/ISO_3166-2) standard. You can also filter the list by name and region codes.

To configure the permissions for your application via OAuth, include the personalize:read or personalize:manage scope.

The Get all Countries request fetches all the country-based information based on the provided search query. The country list is based on the current ISO 3166-1 (https://en.wikipedia.org/wiki/ISO_3166-1) standard.

To configure the permissions for your application via OAuth, include the personalize:read or personalize:manage scope.

The Get all Cities request fetches all the city-based information based on the provided search query. You can also filter the list by name and city codes.

To configure the permissions for your application via OAuth, include the personalize:read or personalize:manage scope.