Skip to main content
Users
Developers
CloudPortalLogin
  • Powered byPowered by
Developing with Sitecore Personalize
Data privacy
Before you start sending data
Integrating with Sitecore Personalize
Stream API
Personalize API Flow execution
REST APIs
  • Sitecore Personalize for developers
  • REST APIs
  • Flow definition REST API
  • Update a flow definition

Update a flow definition

PUT /v3/flowDefinitions/<flowDefinitionRef>

Updates a flow definition. Every update increases the value in the revision key by one.

Attribute

Type

Description

Example

flowDefinitionRef

string

The reference of the flow definition.

If you do not know the flow definition reference, first retrieve flow definitions.

ddfa024b-dd69-4e4d-af78-44d6cf0d7bf8

At a minimum, you must provide the following required attributes in the request body:

Attribute

Type

Description

Example(s)

name

string

The name of the flow definition.

"Alert bar"

friendlyId

string

The unique ID of the flow definition.

Only lowercase alphanumeric characters and underscores are allowed.

"alert_bar_1"

type

string enum (uppercase)

The type of the flow definition.

For a web experiment or experience, set this value to "INTERACTIVE_WEB_FLOW".

For an interactive experiment or experience, set this value to "INTERACTIVE_API_FLOW".

For a triggered experiment or experience, set this value to "TRIGGERED_V3".

Must be one of:

  • "INTERACTIVE_WEB_FLOW"

  • "INTERACTIVE_API_FLOW"

  • "TRIGGERED_V3"

subtype

string enum (uppercase)

The subtype of the flow.

Set this value either to "EXPERIMENT" or "EXPERIENCE".

Must be one of:

  • "EXPERIMENT"

  • "EXPERIENCE"

status

string enum (uppercase)

The status of the flow definition.

When you create an experiment or experience, set this value to "DRAFT".

Must be one of:

  • "DRAFT"

  • "PUBLISHING"

  • "PRODUCTION"

  • "SCHEDULED"

  • "LIVE"

  • "PAUSED"

  • "COMPLETED"

channels

array of uppercase strings (enum)

The touchpoint where the user interacts with your brand.

For example, for webpages, the channel is "WEB". For mobile app screens, the channel is "MOBILE_APP".

Every string must be one of:

  • "CALL_CENTER"

  • "EMAIL"

  • "MOBILE_APP"

  • "MOBILE_WEB"

  • "PUSH_NOTIFICATION"

  • "SMS"

  • "WEB"

businessProcess

string

For a web or interactive experiment or experience, set this value to "interactive_v1".

For a triggered experiment or experience, set this value to "triggered_v1".

  • "interactive_v1"

  • "triggered_v1"

variants

array

Different versions of the same experiment.

For an experience, set this value to an empty array [].

[]

traffic

object

For an experiment, this object determines what percentage of guests should be exposed to each variant of the experiment.

For an experience, this object determines what percentage of guests should be exposed to the experience.

N/A

schedule

object

The time frame for when an experiment or experience can run.

N/A

sampleSizeConfig

object

For an experiment with a primary goal, this object defines A/B test parameters. These parameters affect the minimum sample size required for a test to reach statistical significance.

N/A

The traffic object:

Attribute

Type

Description

Example(s)

type

string enum

The traffic allocation type for an experiment.

For an experience, set this to "simpleTraffic" or "advancedTraffic".

Must be one of:

  • "simpleTraffic"

  • "advancedTraffic"

weightingAlgorithm

string enum

The algorithm that determines the weights given to each variant in an experiment.

Must be one of:

  • "MULTI_ARMED_BANDIT"

  • "USER_DEFINED"

coupled

boolean

This value defines whether the experiment is coupled to other experiments.

For coupled experiments, every guest is assigned a permanent bucket number based on the guest reference.

The bucket number remains the same for the guest across all coupled experiments.

true, false

allocation

integer

Minimum 0. Maximum 100.

For an experiment, set this value to the percentage of guests you want to expose to the experiment.

For an experience, set this value to 100.

100

splits

array of objects

For an experiment, specify how to split traffic across variants.

Each object represents a variant. In each object, ref is the variant reference. split is a number that represents the percentage of traffic the variant should receive.

For an experience, set this value to an empty array [].

N/A

Here's an example of a simpleTraffic traffic for an experiment that exposes 60 percent of guests to one variant, and 40 percent to another:

RequestResponse
{
  "traffic": {
    "type": "simpleTraffic",
    "weightingAlgorithm": "USER_DEFINED",
    "splits": [
      {
        "ref": "71206a12-b1b0-4baa-93ea-a0752a2762b0",
        "split": 60
      },
      {
        "ref": "ffe19d2a-b531-468d-a155-fedf757208e5",
        "split": 40
      }
    ]
  }
}

Here's an example of an advancedTeaffic traffic for an experiment. Guests in buckets 1 to 11 will not be exposed to the experiment. Guests in buckets 12 to 55 will be exposed to one variant, while guests in buckets 56 to 120 will be exposed to another variant.

RequestResponse
{
  "traffic": {
    "type": "advancedTraffic",
    "weightingAlgorithm": "USER_DEFINED",
    "modifiedAt": "2025-07-21T16:09:54.583Z",
    "allocationLow": 12,
    "allocationHigh": 120,
    "splits": [
      {
        "ref": "3e0c4419-5679-47e8-9d95-7f34b074af4b",
        "lowSplit": 12,
        "highSplit": 55
      },
      {
        "ref": "61705a82-a5d2-4a0f-920f-2c0990897b39",
        "lowSplit": 56,
        "highSplit": 120
      }
    ]
  }
}

The schedule object:

Attribute

Type

Description

Example(s)

type

string enum

The type of the flow schedule.

Set this value to "simpleSchedule".

"simpleSchedule"

startDate

string (ISO 8601)

The earliest possible time the flow can run.

2025-07-04T11:46:41.810Z

endDate

optional

string (ISO 8601)

The last possible time the flow can run.

2025-07-22T12:00:00.810Z

The sampleSizeConfig object:

Attribute

Type

Description

Example(s)

baseValue

number

The anticipated conversion goal value of the primary goal.

The default is 0.02.

0.02

minimumDetectableDifference

number

The minimum conversion goal difference to detect relative to the base value.

The default is 0.2.

0.2

confidenceLevel

number

The required confidence level before the test is considered complete.

This value represents the confidence your organization has that if the null hypothesis is true, the measured difference is not due to random fluctuations.

The default is 0.95.

0.95

RequestResponse
curl -X PUT '<baseURL>/v3/flowDefinitions/ddfa024b-dd69-4e4d-af78-44d6cf0d7bf8' \
-H 'Authorization: Bearer <accessToken>' \
-H 'Accept: application/json' \
--data-raw '
{
  "name": "Alert bar 1 - UPDATED",
  "friendlyId": "alert_bar_1",
  "type": "INTERACTIVE_WEB_FLOW",
  "subtype": "EXPERIENCE",
  "status": "DRAFT",
  "channels": [
    "WEB"
  ],
  "traffic": {
    "type": "simpleTraffic",
    "splits": [],
    "weightingAlgorithm": "USER_DEFINED",
    "coupled": false,
    "allocation": 100
  },
  "schedule": {
    "type": "simpleSchedule",
    "startDate": "2025-07-04T11:46:41.810Z"
  },
  "sampleSizeConfig": {
    "baseValue": 0.02,
    "minimumDetectableDifference": 0.2,
    "confidenceLevel": 0.95
  },
  "businessProcess": "interactive_v1",
  "variants": []
}'
RequestResponse
{
  "clientKey": "pqsPERS3lw12v5a9rrHPW1c4hET73GxQ",
  "href": "<baseURL>/v3/flowDefinitions/ddfa024b-dd69-4e4d-af78-44d6cf0d7bf8",
  "ref": "ddfa024b-dd69-4e4d-af78-44d6cf0d7bf8",
  "name": "Alert bar 1 - UPDATED",
  "modifiedByRef": "zwxCA58jwLzfeU2mNGgalCpoJzNVYOJl@clients",
  "modifiedAt": "2025-07-04T14:45:32.922Z",
  "revision": 2,
  "archived": false,
  "friendlyId": "alert_bar_1",
  "type": "INTERACTIVE_WEB_FLOW",
  "subtype": "EXPERIENCE",
  "channels": [
    "WEB"
  ],
  "triggers": [],
  "tags": [],
  "businessProcess": "interactive_v1",
  "traffic": {
    "type": "simpleTraffic",
    "weightingAlgorithm": "USER_DEFINED",
    "modifiedAt": "2025-07-04T14:45:32.922Z",
    "allocation": 100,
    "splits": [],
    "coupled": false
  },
  "variants": [],
  "transpiledVariants": [],
  "status": "DRAFT",
  "schedule": {
    "type": "simpleSchedule",
    "startDate": "2025-07-04T11:46:41.810Z"
  },
  "revisions": {
    "href": "<baseURL>/v3/flowDefinitions/ddfa024b-dd69-4e4d-af78-44d6cf0d7bf8/revisions"
  },
  "sampleSizeConfig": {
    "baseValue": 0.02,
    "minimumDetectableDifference": 0.2,
    "confidenceLevel": 0.95
  }
}

Do you have some feedback for us?

If you have suggestions for improving this article,

Privacy policySitecore Trust CenterCopyright © 1999-2025 Sitecore