Create a new experience

post

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

Creates a new experience (e.g., A/B test, Split URL test, MVT, Deploy, A/A test, Multi-page Funnel) within a project. Requires defining the experience name, type, status (usually 'draft'), and the URL for the Visual Editor or original page. Variations, audiences, locations, goals, and other settings can be specified during creation. The Knowledge Base article "Create a New Experience" outlines the UI process.

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

Query Params

include

array of objects

Specifies the list of optional objects which would be included in the response.

Read more in the section related to Expanding Fields

include

expand

array of objects

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

Request body for creating a new experience. Requires at least name, status, type, and url. Other fields like variations, audiences, goals, and settings are highly recommended for a functional setup.

description

string

length ≤ 500

An optional, detailed explanation of the experience's purpose, hypothesis, or specific changes being tested.

start_time

integer | null

Unix timestamp (UTC) indicating when the experience was first activated (status changed to 'active'). Null or 0 if the experience has never been started.

end_time

integer | null

Unix timestamp (UTC) indicating when the experience was last stopped (e.g., paused or completed). Null or 0 if the experience is currently active or has never been stopped.

global_js

string

Custom JavaScript code that will be executed for all visitors bucketed into this experience, before any variation-specific code is applied. Useful for setting up common functionalities or variables needed by multiple variations. KB: "Project, Experience, Variation Javascript" - "Global Experience JavaScript".

global_css

string

Custom CSS rules that will be applied for all visitors bucketed into this experience, before any variation-specific CSS. Useful for common styling adjustments needed across all variations.

name

string

required

length ≤ 100

A user-defined, friendly name for the experience (e.g., "Homepage Headline Test", "Checkout Funnel Optimization Q3"). This name is prominent in the Convert UI and reports.

key

string

length ≤ 32

A unique, machine-readable key or identifier for this experience within the project. Often auto-generated from the name if not specified, but can be user-defined for easier programmatic reference (e.g., in Full Stack SDKs or API calls). Example: "homepage_headline_test_q3".

primary_goal

integer

The ID of the main conversion goal this experience is intended to optimize. Performance against this primary goal often determines the "winner" of an A/B test and is highlighted in reports. KB: "Experiment Report" - "Primary Goal".

objective

string | null

A detailed statement outlining the objective of this experience. This often includes the hypothesis being tested, the problem it aims to solve, the proposed solution (the variations), and the expected impact on key metrics. Connects to the "Hypotheses (Compass)" feature.

settings

object

Comprehensive settings governing how an experience's results are reported and analyzed.

site_area

object | null

(Deprecated) The legacy way to define on which pages the experience should run, using a set of include/exclude rules based on URL components or page tags. Modern experiences should use the locations array instead for more flexible targeting.

traffic_distribution

number

0 to 100

The percentage of total eligible website traffic (matching audience and location criteria) that will be directed into this entire experience. For example, a value of 50 means 50% of eligible visitors will participate, while the other 50% will see the default website content and not be tracked for this experience. The traffic within the experience is then further split among its variations based on variations[].traffic_distribution. KB: "What is an Traffic Distribution?".

type

string

enum

required

The type of optimization activity:

a/b: Standard A/B test comparing an original page/element against one or more variations. Changes made via Visual Editor or code. KB: "What is an Experiment?".
a/a: Tests the original page against an identical copy of itself to validate tracking setup and ensure no inherent bias. KB: "A/A Experiments".
mvt: Multivariate test, testing combinations of changes across multiple sections of a page. KB: "Creating a Multivariate Experiment".
split_url: Redirects traffic between different URLs to test entirely different page versions. KB: "How do Split URL Experiments work?".
multipage: Tests a consistent set of changes across a sequence of pages (funnel). KB: "Create Multipage Experiences".
deploy: Rolls out a specific set of changes to a targeted audience without A/B comparison reporting. KB: "What about Deployments?".
a/b_fullstack: An A/B test conducted using a Full Stack SDK, potentially involving server-side changes. KB: "Full Stack Experiments on Convert".
feature_rollout: A Full Stack experience for gradually rolling out a new feature, often using feature flags.

url

uri

required

length ≤ 2048

The primary URL used to load the page in Convert's Visual Editor when creating or editing this experience's variations. For Split URL tests, this is typically the URL of the original (control) page.

version

number

An internal version number for the experience, incremented upon certain modifications.

integrations

array

A list of configurations for third-party integrations enabled for this experience (e.g., Google Analytics, Hotjar, Mixpanel). Each object specifies the provider and any provider-specific settings (like a GA Custom Dimension index).

integrations

environments

array of strings

deprecated

(Deprecated) List of environment names where this experience will run. Use the singular environment field instead.

environments

environment

string

The specific environment (e.g., "production", "staging", "development") within the project where this experience is intended to run. This must match one of the environments defined at the project level. If not set, it typically defaults to the project's default environment (often "production"). KB: "The Environments Feature".

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.

multipage_pages

array of objects

An array of page objects, each with an id (unique within this experience, e.g., 'p1'), name, and url. Changes for each of these pages are then defined within the changes array of each variation, referencing the page_id. When updating, this list replaces all existing pages; pages not in the list will be removed.

multipage_pages

status

string

enum

required

The set of statuses a caller may set when creating or updating an experience.

Allowed:

audiences

array of integers

A list of Audience IDs to associate with the experience. Visitors must match criteria from these audiences (according to settings.matching_options.audiences) to be eligible.

audiences

locations

array of integers

A list of Location IDs to associate with the experience. The experience will run on pages/conditions defined by these locations (according to settings.matching_options.locations).

locations

goals

array of integers

A list of Goal IDs to attach to the experience for conversion tracking. The first goal in this list is often implicitly considered the primary_goal unless explicitly set otherwise. Not applicable for 'deploy' type experiences.

goals

201Comprehensive details for a single experience, including its configuration, variations, associated audiences, locations, goals, integrations, and settings.

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.