Add a new section to an MVT experience

post

https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/sections/add

Creates a new section within a multivariate (MVT) experience. A section represents an element or area of the page to be tested with multiple alternatives (versions). Requires defining the section name and its initial versions with their respective changes.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

account_id

integer

required

ID of the account that owns the retrieved/saved data

project_id

integer

required

ID of the project to which save/retrieved data is connected

experience_id

integer

required

The ID of the experience where section will be created

Query Params

include

array of objects

Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default

Read more in the section related to Optional Fields

include

expand

array of strings

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

expand

Body Params

Defines a new section for a Multivariate (MVT) experience. Requires:

id: A unique 1-2 character ID for the section within this experience.
name: A descriptive name for the section (e.g., "Headline Area", "CTA Button Style").
versions: An array defining the initial alternatives (versions) for this section, each with its own set of changes. IMPORTANT: Adding or removing sections impacts MVT variation combinations and can invalidate running tests.

Base properties for a section within a Multivariate (MVT) experience.

string

length between 1 and 2

A unique identifier for this section within the MVT experience (e.g., "s1", "01", "ab"). Typically a short string (1-2 characters). This ID helps in structuring the MVT test.

name

string

length ≤ 200

A user-defined, friendly name for this section (e.g., "Page Headline", "Main Call-to-Action Button", "Hero Image"). This name appears in MVT setup and reports.

concurrency_key

string | null

A server-generated hash that represents the object's state at the time of retrieval. When included in an update request, the operation will only succeed if the object hasn't been modified since this key was obtained. If another update has occurred in the meantime, the request will fail with a conflict error, requiring you to fetch the latest version and retry your update with the new concurrency_key. This implements optimistic concurrency control to prevent lost updates in concurrent scenarios.

versions

array of objects

required

Version definition.

Each Multivariate experience is made of a list of Sections and a list of Versions

Than, variations of a Multivariate experience are made of all possible combinations of versions, takin one from each section.

Example: Experience has Section A and Section B. Section A has Version 1 and Version 2, Section B has Version 3 and Version 4

The resulting experience's variations will be the following:

Section A - Version 1 + Section B - Version 3
Section A - Version 2 + Section B - Version 3
Section A - Version 1 + Section B - Version 4
Section A - Version 1 + Section B - Version 4

versions*

Responses

201A list of sections defined for a multivariate (MVT) experience. Each section includes its id, name, and an array of its versions (alternatives).

defaultIndicates an error occurred while processing the request. The code provides an HTTP status code, message offers a human-readable explanation or an array of validation errors, and fields (if present) specifies which input fields were problematic.