Campaign

Schema, including its fields, nested structure, and relationships

Definition

A Campaign is the top-level resource representing an experiment or personalization campaign. It defines all high-level settings for an experience, such as the campaign name, type (A/B test, multivariate, etc.), status, target pages, and which audience to target. Campaigns contain one or more variations that specify what happens in the campaign. Campaigns can optionally be organized into folders.

Parent Relationship

Parent Resource Type: None
Parent Identifier Field: None
Rule: Campaigns are top-level entities. They do not have a parent resource within the resource loader hierarchy (the actual parent context is typically your account or project, but in this schema, they are considered root). In other words, you do not nest a campaign under any other resource in the JSON structure.

Payload Properties

A campaign has many properties. When creating or updating a campaign, the payload can include the following fields:

id (Integer, optional) – The campaign’s unique ID. Required only for updating an existing campaign. Example: 100000.
name (String, required) – The name of the campaign. This is an internal title to identify the campaign (e.g., "Homepage Banner Test"). Example: "NewBanner" (campaign name).
type (String, required) – The campaign type or format. This defines what kind of test or campaign it is. Common possible values include: "ab" (A/B test), "multipage" (multi-page test), "multivariate" (multivariate test), "mastersegment" (personalization/master segment campaign), or "byapi" (campaign triggered by API). Example: "ab" (indicating a standard A/B test).
url (String, optional) – The primary URL associated with the campaign, if applicable. For A/B tests, this is often the URL of the page being tested (where the variations will run). This field is required for "ab" type campaigns (since an A/B test needs a target URL), but might not be required for other types. Example: "<https://example.com>" (the page on which the test is running).
description (String, optional) – A description of the campaign. You can use this to summarize the campaign’s purpose or any notes. Example: "Testing a new banner on the homepage."
status (String, optional) – The current status of the campaign. Typical statuses might be "draft", "online" (live), "paused", or "archived". This can often be set on creation or updated to pause/play campaigns. Example: "pause" (indicating the campaign is created in a paused state).
labels (Array of Strings, optional) – Tags or labels associated with the campaign. Labels are used for organizing and filtering campaigns in the interface. Example: ["Marketing", "Homepage"].
folder_id (Integer, optional) – The ID of a folder that this campaign belongs to, if any. This links the campaign to a Folder (for organizational grouping). Example: 0 (or an actual folder ID like 12345; 0 might indicate "no folder" in some contexts as seen in the example).
code (String, optional) – An optional global code string for the campaign. This can include global JavaScript should run for this campaign regardless of specific variations.
source_code (String, optional) – An optional code string to load the editor with embedded source code.
campaign_targeting (Object, optional) – An object defining targeting rules directly on the campaign. This is used to specify on which pages or under what conditions the campaign should run, when not using a predefined Audience. It can include:
- segment_ids – an array of audience segment IDs (audience) that are targeted.
- url_scopes – an array of URL targeting conditions (each specifying a URL pattern to include or exclude). For example, you can target pages by URL using conditions like "URL contains X".
- favorite_url_scopes – an array of saved URL conditions (favorites) to include or exclude.
- selector_scopes – an array of on-page element (DOM selector) conditions that must be met. (For instance, ensure a certain CSS selector exists or doesn’t exist on the page to trigger the campaign.)
- code_scope – a code-based, containing a script to run (in value).
- triggers_ids – an array of audience trigger IDs (audience) that are targeted.
- element_appears_after_page_load– a boolean. By default, the targeting checks the existence of your element on page load. If your element may appear after, and you want the tag to keep looking for it, you need to set this to true.
These targeting settings allow complex definition of where and to whom the campaign is displayed. They are typically optional because often a campaign might simply run on a specific URL or use an Audience.
sub_tests (Array of Objects, conditional) – This field holds sub-campaigns if the campaign is of a composite type (such as "multipage", "multivariate", "mastersegment", or "byapi" types). In those cases, the main campaign can contain multiple sub-tests (each sub-test is like a child campaign with its own variations). For example, a multi-page test might have separate sub-tests for each page in the funnel. Each object in sub_tests would have a structure similar to a campaign (with its own name, url, type, etc.). This field is required for campaigns of type "byapi", "multipage", "multivariate", or "mastersegment" (composite campaigns), and not used for simple "ab" campaigns.

Example Campaign Payload: Below is an example of a complex campaign payload for a ab campaign (type "ab"). This illustrates many of the fields described above:

{
  "name": "AB Campaign",
  "url": "URL",
  "description": "string",
  "type": "ab",
  "status": "pause",
  "labels": [
    "stepan.vasnevsky.ext",
    "SP"
  ],
  "code": "string",
  "source_code": "",
  "folder_id": 0,
  "campaign_targeting": {
    "segment_ids": [
      "SEGMENT_ID"
    ],
    "url_scopes": [
      {
        "condition": "IS",
        "value": "<https://abtasty.com>"
      }
    ],
    "favorite_url_scopes": [
      {
        "include": true,
        "favorite_url_id": "FAVORITE_URL"
      }
    ],
    "selector_scopes": [
      {
        "condition": "IS_SELECTOR_CLASS",
        "value": ".h1"
      },
      {
        "condition": "IS_NOT_SELECTOR_ID",
        "value": "#1234"
      },
      {
        "condition": "IS_NOT_SELECTOR_CLASS",
        "value": ".#blue"
      }
    ],
    "code_scope": {
      "value": "console.log('hello world');"
    }
  }
}

In this example:

The campaign is named "AB Campaign" and is currently paused.
It has a primary target URL and some complex targeting rules (segment IDs, URL scopes, etc.) defined in campaign_targeting.
It’s of type "ab" .

Note: This example is for illustration. In many simple cases, a campaign payload might be much simpler (just a name, type, URL, and maybe an audience or simple targeting). You would typically not specify every field; many are optional or auto-managed.

Response Fields

When a Campaign is retrieved from the API (for example, via an API or the resource loader), it will include all the fields above (with the same structure), plus some additional read-only information. Key response-only fields include:

id (Integer) – The unique ID of the campaign (assigned by the API).
name (String, required) – The name of the campaign. This is an internal title to identify the campaign (e.g., "Homepage Banner Test"). Example: "NewBanner" (campaign name).
type (String, required) – The campaign type or format. This defines what kind of test or campaign it is. Common possible values include: "ab" (A/B test), "multipage" (multi-page test), "multivariate" (multivariate test), "mastersegment" (personalization/master segment campaign), or "byapi" (campaign triggered by API). Example: "ab" (indicating a standard A/B test).
url (String, optional) – The primary URL associated with the campaign, if applicable. For A/B tests, this is often the URL of the page being tested (where the variations will run). This field is required for "ab" type campaigns (since an A/B test needs a target URL), but might not be required for other types. Example: "<https://example.com>" (the page on which the test is running).
description (String, optional) – A description of the campaign. You can use this to summarize the campaign’s purpose or any notes. Example: "Testing a new banner on the homepage."
status (String, optional) – The current status of the campaign. Typical statuses might be "draft", "online" (live), "paused", or "archived". This can often be set on creation or updated to pause/play campaigns. Example: "pause" (indicating the campaign is created in a paused state).
labels (Array of Strings, optional) – Tags or labels associated with the campaign. Labels are used for organizing and filtering campaigns in the interface. Example: ["Marketing", "Homepage"].
created_at (Object) – When the campaign was created (with readable_date, timestamp, pattern as described).
updated_at (Object) – When the campaign was last updated (same structure as above).
last_pause (Object) – If the campaign was paused, when the last pause happened (timestamp in similar format).
last_play (Object) – If the campaign was restarted (unpaused), the time of last reactivation.
...

Additionally, the response will contain the variations belonging to the campaign. In the resource loader output, a campaign typically includes an array of its Variation objects. For example, you might see:

Example Campaign Response:

{
  "id": 100000,
  "name": "Holiday Promo",
  "description": "Winter discounts",
  "type": "ab",
  "url": "URL",
  "status": "draft",
  "created_at": {
    "pattern": "Y-m-d\\TH:i:sO",
    "readable_date": "2025-09-18T08:36:32+0000",
    "timestamp": 1758184592
  },
  "variations": [
    {
      "id": 200000,
      "name": "Variation 1",
      "traffic": 50,
      "type": "onthefly"
    }
  ],
  "labels": [
    "chadi.laoulaou"
  ],
  "last_pause": {
    "pattern": "Y-m-d\\TH:i:sO",
    "readable_date": "",
    "timestamp": 0
  },
  "last_play": {
    "pattern": "Y-m-d\\TH:i:sO",
    "readable_date": "",
    "timestamp": 0
  },
  "report": {
    "comment": "",
    "token": "TOKEN"
  }
}

Error Codes

Error scenarios for campaigns largely follow the general codes:

InvalidPayload – The campaign payload is missing required fields or has invalid values (e.g., missing name or type).
ParentNotFound – (Not usually applicable to campaigns since they have no parent in this schema; this might be returned if an account or environment context is wrong, but not in the resource schema context of parent-child).
PermissionDenied – The user lacks permission to create or modify campaigns (for instance, not having the rights to create campaigns in the account).
DuplicateRef – A campaign with the same reference already exists. For example, trying to create a campaign with a name or key that conflicts with an existing one could trigger this.
InvalidDependency – If the campaign references something that doesn’t exist. This is rare at the campaign level, but could occur if sub_tests or audiences reference invalid IDs (e.g., an audience ID that is not found).

PreviousVariation NextFolder

Last updated 11 days ago

Was this helpful?