Convert Accounts API
Account is the entity that contains all data. An account is owned by an user and in which more other users can have different permissions, account wide or at project level
Account is the entity that contains all data. An account is owned by an user and in which more other users can have different permissions, account wide or at project level
openapi: 3.1.0
info:
title: Convert Accounts API
description: 'Move your app forward with the Convert API. The Convert API allows
you to manage your Convert Experiences projects using code. The REST API is
an interface for managing and extending functionality of Convert. For
example, instead of creating and maintaining projects using the Convert
Experiences web dashboard you can create an experiment programmatically.
Additionally, if you prefer to run custom analysis on experiment results you
can leverage the API to pull data from Convert Experiences into your own
workflow. If you do not have a Convert account already, sign up for a free
developer account at https://www.convert.com/api/.
*[Convert API V1](/doc/v1) is still available and documentation can be found [here](/doc/v1) but using it is highly discouraged
as it will be phased out in the future*
'
version: 2.0.0
servers:
- url: https://api.convert.com/api/v2
description: Live API server
- url: https://apidev.convert.com/api/v2
description: DEV API server
- url: http://apidev.convert.com:5000/api/v2
description: DEV mocked API server
tags:
- name: Accounts
description: 'Account is the entity that contains all data. An account is owned by an user and in which more other users can have different permissions, account wide or at project level
'
paths:
/accounts:
get:
operationId: getAccountsList
summary: List accounts accessible to the user
description: 'Retrieves a list of all accounts the authenticated user has access to.
If using API key authentication, this typically returns the single account associated with the API key.
If using cookie-based authentication, it may return multiple accounts if the user is a collaborator on several.
An account is the top-level container for projects, billing, and user management.
'
tags:
- Accounts
responses:
'200':
$ref: '#/components/responses/AccountsListResponse'
/billing-plans:
get:
operationId: getBillingPlans
summary: List available billing plans
description: 'Retrieves a list of all active billing plans that an account can subscribe to.
Each plan defines usage limits (e.g., tested visitors, number of projects) and available features.
'
tags:
- Accounts
responses:
'200':
$ref: '#/components/responses/BillingPlansListResponse'
/accounts/{account_id}/livedata:
post:
operationId: getAccountLiveData
summary: Get live tracking events for an account
tags:
- Accounts
parameters:
- name: account_id
in: path
required: true
description: ID of the account to be retrieved
schema:
type: integer
description: 'Retrieves the last 100 tracking events (e.g., experiment views, goal conversions) across all projects within the specified account.
Useful for real-time monitoring of activity. Supports filtering by event types and specific projects.
As per the Knowledge Base, "Live Logs in Convert track how end users are interacting with web pages and experiments...at a project and experiment level in real time."
'
requestBody:
$ref: '#/components/requestBodies/GetAccountLiveDataRequest'
responses:
'200':
$ref: '#/components/responses/LiveDataEventsListResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/change-history:
post:
operationId: getAccountHistory
summary: Get change history for an account
tags:
- Accounts
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
description: 'Retrieves a historical log of changes made within the specified account, such as modifications to account settings or billing.
This provides an audit trail for account-level activities.
The Knowledge Base states, "The Change History shows a record of user activity for each of your projects." This extends to account changes.
'
requestBody:
$ref: '#/components/requestBodies/GetAccountHistoryRequest'
responses:
'200':
$ref: '#/components/responses/ChangeHistoryListResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/experiences:
post:
operationId: getAccountActiveCompletedExperiencesList
summary: List active and completed experiences for an account
description: 'Retrieves a list of all active and completed experiences (A/B tests, personalizations, etc.) across all projects within the specified account.
Allows filtering to narrow down results. Useful for an overview of ongoing and finished optimization activities at the account level.
'
tags:
- Accounts
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/GetAccountActiveCompletedExperiencesListRequest'
responses:
'200':
$ref: '#/components/responses/ExperiencesListResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/details:
get:
operationId: getAccountDetails
summary: Get details for a specific account
description: 'Retrieves detailed information about a specific account, including its settings, billing status, and usage limits.
The `include` parameter can be used to fetch additional related data, like active project counts.
'
tags:
- Accounts
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: include
in: query
required: false
description: 'Specifies the list of fields to be included in the response, which otherwise would not be sent.
Read more in the section related to [Optional Fields](#tag/Optional-Fields)
'
schema:
type: array
items:
$ref: '#/components/schemas/AccountDetailsIncludeFields'
responses:
'200':
$ref: '#/components/responses/AccountDetailsResponse'
post:
operationId: updateAccountDetails
summary: Update details for a specific account
description: 'Modifies the settings or billing information for a specific account.
This can include updating company details, contact information, or billing preferences.
'
tags:
- Accounts
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/UpdateAccountDetailsRequest'
responses:
'200':
$ref: '#/components/responses/AccountDetailsResponse'
/accounts/{account_id}/sub-accounts/add:
post:
operationId: createSubAccount
summary: Create a new sub-account
description: 'Creates a new sub-account under the specified parent main account.
Sub-accounts inherit certain properties and limits from the parent but can have their own users and projects.
This is typically used by agencies or larger organizations to manage client accounts or departmental usage separately.
'
tags:
- Accounts
parameters:
- name: account_id
in: path
required: true
description: ID of the parent account under which the sub-account is being created.
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/CreateSubAccountRequest'
responses:
'200':
$ref: '#/components/responses/AccountDetailsResponse'
/accounts/{account_id}/addons:
post:
operationId: requestAccountAddons
summary: Request add-ons for an account
description: 'Allows requesting specific add-on features or services for an account, such as premium support tiers or specialized training.
'
tags:
- Accounts
parameters:
- name: account_id
in: path
required: true
description: ID of the account for which the addons will be requested
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/RequestAccountAddonsRequest'
responses:
'200':
$ref: '#/components/responses/SuccessResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/payment-setup:
post:
operationId: startPaymentSetup
summary: Initiate payment method setup
description: 'Starts a secure session with the payment provider (e.g., Stripe) to set up or update an account''s payment method.
Returns a client secret or token that the frontend UI uses to complete the payment setup process directly with the provider.
'
tags:
- Accounts
parameters:
- name: account_id
in: path
required: true
description: ID of the account for which the payment setup will be started
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/StartPaymentSetupRequest'
responses:
'200':
$ref: '#/components/responses/StartPaymentSetupResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/billing-portal:
get:
operationId: getAccountBillingPortal
summary: Get billing portal URL
description: 'Returns an authenticated Paddle billing portal URL for the given account.
The URL takes the customer to the Paddle billing portal where they can
check subscriptions, view or download invoices.
'
tags:
- Accounts
parameters:
- $ref: '#/components/parameters/AccountId'
responses:
'200':
$ref: '#/components/responses/BillingPortalResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/plan_setup/users:
get:
operationId: BillingPlanSetupUsers
summary: Get users for billing plan setup notification
description: 'Retrieves a list of users associated with an account, typically for the purpose of notifying them about billing plan setup or changes.
Used internally for account management workflows.
'
tags:
- Accounts
parameters:
- name: account_id
in: path
required: true
description: ID of the account for which the plan setup users will be returned
schema:
type: integer
responses:
'200':
$ref: '#/components/responses/PlanSetupUsersResponse'
default:
$ref: '#/components/responses/ErrorResponse'
components:
schemas:
ReportingSegmentsCountry:
type: string
description: 'The two-letter ISO 3166-1 alpha-2 country code of the visitor, determined by IP geolocation.
Used for segmenting reports by country to analyze geographical performance.
Knowledge Base: "How Do I Target by Geographic Location Like City, Region or Country?".
'
maxLength: 2
minLength: 2
SimpleLocationExpandable:
anyOf:
- type: integer
description: Location ID
- $ref: '#/components/schemas/SimpleLocation'
PlanSetupUsersResponseData:
type: object
description: A list of users associated with an account, intended for notification during billing plan setup or changes.
properties:
data:
description: Array of user details.
type: array
items:
type: object
properties:
user_id:
type: string
description: The user's unique identifier within the Convert system.
email:
type: string
description: The user's email address.
name:
type: string
description: The user's full name.
ReportingSegmentsSource:
type: string
description: 'The traffic source that brought the visitor to the site (e.g., ''google'', ''facebook.com'', ''direct'', ''newsletter'').
Derived from `utm_source` URL parameters or the HTTP referrer. Enables report segmentation by traffic source.
Knowledge Base: "How Do You Fill Medium, Keyword and Source Name?".
'
enum:
- campaign
- search
- referral
- direct
- ai_tool
RuleElement:
oneOf:
- $ref: '#/components/schemas/GenericTextMatchRule'
- $ref: '#/components/schemas/GenericNumericMatchRule'
- $ref: '#/components/schemas/GenericBoolMatchRule'
- $ref: '#/components/schemas/GenericTextKeyValueMatchRule'
- $ref: '#/components/schemas/GenericNumericKeyValueMatchRule'
- $ref: '#/components/schemas/GenericBoolKeyValueMatchRule'
- $ref: '#/components/schemas/CookieMatchRule'
- $ref: '#/components/schemas/CountryMatchRule'
- $ref: '#/components/schemas/LanguageMatchRule'
- $ref: '#/components/schemas/GoalTriggeredMatchRule'
- $ref: '#/components/schemas/SegmentBucketedMatchRule'
- $ref: '#/components/schemas/DayOfWeekMatchRule'
- $ref: '#/components/schemas/HourOfDayMatchRule'
- $ref: '#/components/schemas/MinuteOfHourMatchRule'
- $ref: '#/components/schemas/BrowserNameMatchRule'
- $ref: '#/components/schemas/OsMatchRule'
- $ref: '#/components/schemas/WeatherConditionMatchRule'
- $ref: '#/components/schemas/VisitorTypeMatchRule'
- $ref: '#/components/schemas/JsConditionMatchRule'
discriminator:
propertyName: rule_type
mapping:
url: '#/components/schemas/GenericTextMatchRule'
url_with_query: '#/components/schemas/GenericTextMatchRule'
query_string: '#/components/schemas/GenericTextMatchRule'
campaign: '#/components/schemas/GenericTextMatchRule'
keyword: '#/components/schemas/GenericTextMatchRule'
medium: '#/components/schemas/GenericTextMatchRule'
source_name: '#/components/schemas/GenericTextMatchRule'
avg_time_page: '#/components/schemas/GenericNumericMatchRule'
city: '#/components/schemas/GenericTextMatchRule'
country: '#/components/schemas/CountryMatchRule'
region: '#/components/schemas/GenericTextMatchRule'
days_since_last_visit: '#/components/schemas/GenericNumericMatchRule'
language: '#/components/schemas/LanguageMatchRule'
pages_visited_count: '#/components/schemas/GenericNumericMatchRule'
goal_triggered: '#/components/schemas/GoalTriggeredMatchRule'
visit_duration: '#/components/schemas/GenericNumericMatchRule'
cookie: '#/components/schemas/CookieMatchRule'
visitor_type: '#/components/schemas/VisitorTypeMatchRule'
visits_count: '#/components/schemas/GenericNumericMatchRule'
bucketed_into_experience: '#/components/schemas/GenericBoolMatchRule'
bucketed_into_segment: '#/components/schemas/SegmentBucketedMatchRule'
local_time_day_of_week: '#/components/schemas/DayOfWeekMatchRule'
local_time_hour_of_day: '#/components/schemas/HourOfDayMatchRule'
local_time_minute_of_hour: '#/components/schemas/MinuteOfHourMatchRule'
project_time_day_of_week: '#/components/schemas/DayOfWeekMatchRule'
project_time_hour_of_day: '#/components/schemas/HourOfDayMatchRule'
project_time_minute_of_hour: '#/components/schemas/MinuteOfHourMatchRule'
browser_name: '#/components/schemas/BrowserNameMatchRule'
browser_version: '#/components/schemas/GenericTextMatchRule'
os: '#/components/schemas/OsMatchRule'
user_agent: '#/components/schemas/GenericTextMatchRule'
is_desktop: '#/components/schemas/GenericBoolMatchRule'
is_mobile: '#/components/schemas/GenericBoolMatchRule'
is_tablet: '#/components/schemas/GenericBoolMatchRule'
js_condition: '#/components/schemas/JsConditionMatchRule'
page_tag_page_type: '#/components/schemas/GenericTextMatchRule'
page_tag_category_id: '#/components/schemas/GenericTextMatchRule'
page_tag_category_name: '#/components/schemas/GenericTextMatchRule'
page_tag_product_sku: '#/components/schemas/GenericTextMatchRule'
page_tag_product_name: '#/components/schemas/GenericTextMatchRule'
page_tag_product_price: '#/components/schemas/GenericNumericMatchRule'
page_tag_customer_id: '#/components/schemas/GenericTextMatchRule'
page_tag_custom_1: '#/components/schemas/GenericTextMatchRule'
page_tag_custom_2: '#/components/schemas/GenericTextMatchRule'
page_tag_custom_3: '#/components/schemas/GenericTextMatchRule'
page_tag_custom_4: '#/components/schemas/GenericTextMatchRule'
weather_condition: '#/components/schemas/WeatherConditionMatchRule'
generic_text_key_value: '#/components/schemas/GenericTextKeyValueMatchRule'
generic_numeric_key_value: '#/components/schemas/GenericNumericKeyValueMatchRule'
generic_bool_key_value: '#/components/schemas/GenericBoolKeyValueMatchRule'
ReportingSegmentsFilters:
type: object
description: 'A collection of filters used to segment experience report data based on various visitor attributes and traffic sources.
Applying these filters allows for deeper analysis of how different user groups interact with experience variations.
Knowledge Base: "Using Basic and Advanced Post segmentation".
'
properties:
devices:
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsDeviceCategories'
nullable: true
browsers:
description: Filter report data for visitors using one or more specified web browsers.
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsBrowser'
nullable: true
countries:
description: Filter report data for visitors from one or more specified countries (using 2-letter ISO codes).
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsCountry'
nullable: true
visitor_types:
description: Filter report data for 'new' or 'returning' visitors.
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsVisitorType'
nullable: true
campaigns:
description: Filter report data for visitors attributed to one or more specified marketing campaign names (from `utm_campaign`).
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsCampaign'
nullable: true
custom_segments:
description: Filter report data for visitors belonging to one or more specified custom Convert Audience segments (by segment ID).
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsCustomSegment'
nullable: true
sources:
description: Filter report data for visitors from one or more specified traffic sources (e.g., 'direct', 'search', 'referral').
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsSource'
nullable: true
AccountDetailsIncludeFields:
type: string
enum:
- stats
- settings.tracking_script.available_versions
VisitorTypeMatchRulesTypes:
type: string
enum:
- visitor_type
LocationTriggerTypes:
type: string
default: upon_run
description: 'Specifies the mechanism that activates an experience when its location rules are met:
- `upon_run`: (Default) The experience activates as soon as the Convert tracking script loads and evaluates that the visitor matches the location''s rules (e.g., URL match). This is the standard behavior for most A/B tests.
- `manual`: The experience only activates when explicitly triggered by a JavaScript call (`window._conv_q.push({ what: ''triggerLocation'', params: { locationId: ''...'' } })`). Gives precise programmatic control over activation.
- `dom_element`: The experience activates upon a specific user interaction (e.g., ''click'', ''hover'', ''in_view'', ''change'') with a defined DOM element (identified by a CSS `selector`). Useful for testing changes related to interactive elements.
- `callback`: The experience activates when a custom JavaScript `callback` function (provided in `js`) calls the `activate()` function passed to it. Allows for complex asynchronous activation logic, e.g., after an API response or a specific SPA state change.
Note: For Full Stack projects, `upon_run` is effectively the only mode, as activation is handled by the SDK.
'
enum:
- upon_run
- manual
- dom_element
- callback
SubAccountProductsCreate:
type: object
properties:
billing:
type: object
required:
- products
properties:
products:
type: object
description: Specifies initial plan subscriptions for Convert products.
required:
- experiences
properties:
experiences:
type: object
description: Initial plan for the 'Experiences' product.
required:
- plan
properties:
plan:
required:
- product
- usageLimits
allOf:
- $ref: '#/components/schemas/SubAccountBillingPlanData'
LocationExpandable:
anyOf:
- type: integer
description: Location ID
- $ref: '#/components/schemas/Location'
AudienceExpandable:
anyOf:
- type: integer
description: Audience ID
- $ref: '#/components/schemas/Audience'
ProjectStatuses:
description: 'The overall status of a project:
- `active`: The project is active, and experiences within it can run and track data.
- `inactive`: The project is inactive (archived or paused). No experiences within it will run, and no new data will be tracked.
- `suspended`: The project (or account) has been suspended, typically due to billing issues or terms of service violations. Services are disabled.
'
type: string
enum:
- active
- inactive
- suspended
ExperienceChangeIdReadOnly:
description: Represents the unique identifier of a change, typically when returned by the API after creation or in a list.
type: object
properties:
id:
description: The unique numerical identifier for this specific change.
type: integer
readOnly: true
ExperienceChangeBase:
description: The fundamental structure representing a single modification applied within an experience's variation. The specific content and behavior of the change are determined by its `type` and detailed in the `data` object.
type: object
properties:
type:
type: string
enum:
- richStructure
- customCode
- defaultCode
- defaultCodeMultipage
- defaultRedirect
- fullStackFeature
data:
description: 'A flexible object containing the specific details and content for this change, structured according to the change `type`.
For example, for `customCode`, it would contain `js` and `css` strings. For `defaultRedirect`, it would contain `original_pattern` and `variation_pattern`.
This field is included by default when fetching a single `ExperienceChange` but might be omitted in list views unless specified in an `include` parameter.
'
type: object
UserCustomization:
description: A generic key-value pair for storing miscellaneous user-specific UI customizations or settings not covered by structured preferences.
type: object
properties:
key:
type: string
maxLength: 20
value:
nullable: true
oneOf:
- type: string
maxLength: 20
- type: number
- type: boolean
required:
- key
- value
BaseProject:
type: object
properties:
global_javascript:
type: string
nullable: true
description: 'Custom JavaScript code that will be included on all pages where this project''s tracking script is installed.
This script runs before any experience-specific code, making it suitable for global helper functions, third-party integrations setup (like analytics), or defining global variables.
KB: "Project, Experience, Variation Javascript" - "Global Project JavaScript".
'
name:
type: string
maxLength: 200
description: A user-defined, friendly name for the project (e.g., "Main Website Optimization", "Q3 Marketing Campaigns", "Mobile App Features").
project_type:
type: string
description: 'The type of project, determining its capabilities and how it''s used:
- `web`: For traditional website A/B testing, MVT, Split URL, personalization, and deploys using the client-side JavaScript tracking snippet.
- `fullstack`: For server-side experiments, feature flagging, and mobile app testing using Convert''s Full Stack SDKs.
KB: "Full Stack Experiments on Convert".
'
enum:
- web
- fullstack
default: web
reporting_settings:
allOf:
- type: object
description: Project settings used for reporting
properties:
tested_visitors_quota:
type: integer
minimum: 0
description: Maximum number of tested visitors that is allowed to go through this project in a billing cycle. After that number has been reached, no experiences that have influence over tested visitors will run in this project.
currency_symbol:
type: string
description: Currency symbol used in the reporting.
maxLength: 10
blocked_ips:
type: object
nullable: true
properties:
single:
type: array
description: List of single ip addresses blocked.
items:
type: object
minProperties: 1
properties:
value:
type: string
format: ip-address
name:
type: string
nullable: true
maxLength: 64
required:
- value
range:
type: array
description: List of ip addresses range.
items:
type: object
minProperties: 1
properties:
start:
type: string
format: ip-address
description: Starts from ip.
end:
type: string
format: ip-address
description: Ends with ip.
name:
type: string
nullable: true
maxLength: 64
required:
- start
- end
description: A list of blocked IPs that are not allowed to be counted in the reports
stop_tracking_goals_after_days:
type: string
description: 'Defines goals tracking life time: goals won''t be tracking after specified days unless used in active experiments.'
enum:
- 'OFF'
- 1 day
- 15 days
- 30 days
- 60 days
smart_recommendations:
type: boolean
default: true
description: 'Whether to run or not Smart Recommendations.
'
keep_running_until_confidence:
type: boolean
description: 'If true, experiments do not auto-complete when planned sample size (100% progress) is reached alone.
They only auto-complete when both planned sample size is reached and the confidence threshold is met.
If false, experiments complete automatically when planned sample size is reached, regardless of confidence level.
Default depends on automation toggle: when keep_winner or stop_loser is enabled, default is true; otherwise false.
'
- $ref: '#/components/schemas/ExperienceReportingSettings'
settings:
type: object
description: General operational settings for the project.
properties:
allow_crossdomain_tracking:
type: boolean
description: 'If true, enables automatic passing of Convert tracking cookies (`_conv_v`, `_conv_s`) as URL parameters when visitors navigate between different domains listed in this project''s `Active Websites`.
Essential for maintaining consistent visitor identity and experiment bucketing across multiple domains (e.g., main site to a separate checkout domain).
KB: "Cookies and Cross-Domain Testing".
'
allow_gdpr:
type: boolean
description: 'If true, displays GDPR-related warnings in the Convert UI for settings or features that might have privacy implications (e.g., using certain audience conditions, enabling cross-domain tracking).
KB: "GDPR warnings".
'
data_anonymization:
type: boolean
description: 'If true, masks the names of experiences, variations, segments, and goals in the public JavaScript tracking snippet and in data sent to some third-party integrations.
Instead of names, their numerical IDs are used. Enhances privacy by preventing public disclosure of experiment details.
KB: "Prevent Experiment Details Data Leak with Data Anonymization".
'
do_not_track:
type: string
enum:
- 'OFF'
- EU ONLY
- EEA ONLY
- Worldwide
description: 'Configures if and how the project respects the "Do Not Track" (DNT) browser setting sent by visitors.
- `OFF`: DNT signals are ignored.
- `EU ONLY`: Respects DNT for visitors from EU countries.
- `EEA ONLY`: Respects DNT for visitors from European Economic Area countries.
- `Worldwide`: Respects DNT for all visitors globally.
If respected, the Convert script may not load or track for visitors with DNT enabled.
KB: "Respect Browser Do Not Track Setting".
'
global_privacy_control:
type: string
enum:
- 'OFF'
- EU ONLY
- EEA ONLY
- Worldwide
description: 'Configures if and how the project respects Global Privacy Control (GPC) signals sent by visitors'' browsers.
Options are similar to `do_
# --- truncated at 32 KB (254 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/convert/refs/heads/main/openapi/convert-accounts-api-openapi.yml