Flow definition REST API

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`

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.	`"mys3cr3tstr1ingforauth1!x"`
`schedule`	object	The time frame for when an experiment or experience can run.	`"mys3cr3tstr1ingforauth1!x"`
`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.	`"mys3cr3tstr1ingforauth1!x"`

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 `[]`.	`"mys3cr3tstr1ingforauth1!x"`

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:

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

{
  "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`

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`

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

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": []
}'

{
  "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
  }
}

If you have suggestions for improving this article, let us know!