Create a new hypothesis

post

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

Defines a new hypothesis within a project. Requires a name, objective (problem and proposed solution), prioritization model (PIE or ICE) and its scores, status, and optionally, start/end dates, summary, associated experiences, and tags. The Knowledge Base article "Hypotheses (Compass)" details the PIE (Potential, Importance, Ease) and ICE (Impact, Confidence, Ease) models.

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 into which the hypothesis is to be stored

Query Params

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

name

string

required

length ≤ 100

A user-defined, concise name for the hypothesis (e.g., "Changing CTA Button Color to Green", "Simplifying Signup Form"). This name appears in the Compass section of Convert.

url

string | null

(Optional) A URL relevant to this hypothesis, such as the page where the proposed change would be implemented or a link to supporting research/data.

objective

string

length ≤ 5000

A detailed description of the hypothesis. This should clearly state:

The problem observed (e.g., "Low click-through rate on the main CTA").
The proposed solution/change (e.g., "Change the CTA button text from 'Learn More' to 'Get Started Now'").
The expected outcome/impact (e.g., "This will increase clicks on the CTA by 15% because 'Get Started Now' is more action-oriented"). KB: "Hypotheses (Compass)" - "What is a Hypothesis".

status

string

enum

required

The current stage or outcome of a hypothesis in its lifecycle:

draft: The hypothesis is still being formulated or refined; not yet ready for testing.
completed: The hypothesis definition is finalized and it's ready to be linked to an experiment or tested.
applied: The hypothesis is currently being tested in one or more active experiences.
proven: Testing has concluded, and the hypothesis was validated (i.e., the proposed change led to a positive, statistically significant outcome). Can be moved to Knowledge Base.
disproven: Testing has concluded, and the hypothesis was invalidated (i.e., the proposed change did not lead to the expected positive outcome or had a negative impact). Can be moved to Knowledge Base.
archived: The hypothesis is no longer active or relevant for current testing but is kept for historical records. KB: "Hypotheses (Compass)" - "Status of Hypothesis".

Allowed:

start_date

date | null

(Optional) The date (YYYY-MM-DD) when this hypothesis was conceptualized or formally logged.

end_date

date | null

(Optional) The target date (YYYY-MM-DD) by which this hypothesis is expected to be tested or resolved.

summary

string

length ≤ 500

(Optional) A brief summary or key takeaway from this hypothesis, often filled in after testing.

description

string | null

This is more details that want to be added besides the name of the hypothesis

files

array of objects | null

Files attached to the hypothesis

files

created_at

integer

Unix timestamp (UTC) indicating when this hypothesis was created in the system.

prioritization_score_type

string

enum

required

A given description of prioritizing model

Allowed:

prioritization_score_attributes

object

required

Scores for the PIE (Potential, Importance, Ease) prioritization model. Each attribute is scored on a scale of 1 to 5. KB: "Hypotheses (Compass)" - "PIE prioritization model".

experiences

array of integers

length ≤ 100

A list of experience IDs that are testing or were derived from this hypothesis. This links the hypothesis to actual experiments.

experiences

201Detailed information for a single hypothesis, including its name, objective, prioritization model (PIE/ICE) and scores, status, start/end dates, summary, and links to associated experiences and tags.

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.