Create or update a personalization

POST

/api/v1/personalizations

Create a new personalization (experience), or update an existing one by passing its variationId.

Notes

• websiteId is taken from the auth headers and overwrites whatever the body says
• variationName is required; the request is rejected without it
• Deleting a personalization, duplicating one and managing themes are not available with an API key, only from the dashboard

Parameters

Header Parameters

x-api-key

required

string

Your API key from account settings.

x-user-email

required

string

The email address of your user.

x-account-id

required

string

The ID of your account. You can find this in the account settings.

x-website-id

required

string

The ID of the workspace you want to use.

Request Body ^required

object

accountId

The account ID that owns this personalization.

string

nullable

assignee

User assigned to this personalization.

string

nullable

changed

Whether the personalization has been modified.

boolean

nullable

componentAccountId

Account ID for component-based personalizations.

string

nullable

componentPackageName

Package name for component-based personalizations.

string

nullable

componentSettings

JSON string containing component configuration.

string

nullable

componentType

Type of component used.

string

nullable

componentVersion

Version of the component.

number

nullable

createdAt

Timestamp when personalization was created.

number

nullable

createdDate

Creation date timestamp.

number

nullable

delayOption

Delay trigger option (e.g., “seconds”, “pageviews”).

string

nullable

delayValue

Delay value for trigger timing.

number

nullable

diffUrl

URL for viewing changes diff.

string

nullable

disabled

Whether the personalization is disabled.

boolean

nullable

endDate

Timestamp when personalization should stop running.

number

nullable

excludedRule

Rules for excluding visitors.

string

nullable

exclusive

Whether this personalization is exclusive.

boolean

nullable

hideOption

Option for hiding the personalization.

string

nullable

hideValue

Value for hide timing.

number

nullable

isComponent

Whether this is a component-based personalization.

boolean

nullable

isHiddenAiComponent

Whether this is a hidden AI component.

boolean

nullable

javascriptTrigger

JavaScript trigger code.

string

nullable

javascriptTriggerParsed

Parsed JavaScript trigger.

string

nullable

longurl

Extended URL information.

string

nullable

maxValue

Maximum value for certain triggers.

number

nullable

personalizationTags

Array of tags associated with this personalization.

Array<string>

nullable

prio

Priority level (higher numbers = higher priority).

number

nullable

recipe

Personalization recipe/template.

string

nullable

redirectUrl

URL for redirect-type personalizations.

string

nullable

rule

Targeting rules in JSON format.

string

nullable

startDate

Timestamp when personalization should start running.

number

nullable

state

Current state (e.g., “running”, “paused”, “draft”).

string

nullable

targetTemplateDomain

Target domain for template.

string

nullable

targetTemplatePath

Target path for template.

string

nullable

testMode

Test mode configuration.

string

nullable

updatedDate

Timestamp of last update.

number

nullable

variants

Array of personalization variants.

Array<object>

nullable

object

variationId

ID of the variation.

string

nullable

variationName

Name of the variation.

string

nullable

webPagePath

Web page path where personalization applies.

string

nullable

websiteId

Website ID this personalization belongs to.

string

nullable

variationId

ID of an existing personalization to update. Omit to create a new one.

string

variationName

required

Name of the variation being saved.

string

Example

{
  "name": "Homepage hero test",
  "variationName": "Control",
  "state": "draft",
  "webPagePath": "/"
}

Responses

200

The created or updated personalization.

400

Bad request - missing websiteId or variationName.

401

Unauthorized - invalid API key.