Campaigns API reference
Manage campaign content changes, audience references, goals, and holdback settings in the project draft.
Use campaigns to change content on existing website pages for selected audiences. This API flattens a campaign's variants and actions into a changes array.
Authentication and campaign operations
Paths below follow https://api.rightmessage.com/v1/{teamPid}. GET requires read or write; mutations require write. The * ability satisfies both. The shared request conventions cover bearer authentication, headers, project access, and rate limits.
| Method and path | Request | Success |
|---|---|---|
GET /campaigns | No filters or pagination parameters | 200, {"data":[RESOURCE]} |
GET /campaigns/{campaign} | Resource ID from the list | 200, {"data":RESOURCE} |
POST /campaigns | Create body below | 201, {"data":RESOURCE} |
PUT or PATCH /campaigns/{campaign} | Partial body below | 200, {"data":RESOURCE} |
DELETE /campaigns/{campaign} | No body | 204, empty body |
PUT and PATCH have the same partial-update behavior. An omitted top-level field retains its value. A collection with no resources returns {"data":[]}. Reads return the draft when one exists, otherwise the stable configuration.
Errors and draft effects
The shared error contract applies. Invalid request fields return 422 with message and field-keyed errors. Full-configuration validation can return 500 instead.
Mutations save a draft, not live changes. Publishing applies the whole project draft, including edits made elsewhere. The draft contract covers snapshots, dashboard updates, and save failures.
Campaign fields
| Field | Type and validation | Create default |
|---|---|---|
name | Required on create, optional on update. String, maximum 255. | Required |
is_active | Boolean | true |
base_url | Nullable string, maximum 500. No URL-format validation. | null |
testing | Object | Enabled with 10 percent holdback |
testing.is_enabled | Boolean | true |
testing.withhold | Integer, 0 through 100 | 10 |
goal_ids | Array of strings | [] |
outcome | any_goal or primary_goal | any_goal |
changes | Array of change objects | [] |
A supplied goal_ids list replaces the list. With primary_goal, the first attached goal is primary. A supplied testing object replaces the stored object, except that omitted withhold retains its previous value. Configuration repair fills an omitted is_enabled with true, even if testing was previously disabled. Send both testing fields when changing testing settings.
Change objects
Every field below belongs in each changes[] item. Except for selector requirements, every field is optional and nullable.
| Field | Type and meaning |
|---|---|
id | String identifying the stored action. Omit for a new action. |
variant_id | String identifying its stored variant. Use with id to disambiguate repeated legacy action IDs. |
selector | CSS-selector string. Required on create unless targeting is supplied. On update, required unless id or targeting is supplied. |
targeting | Object with mode of selector or fingerprint; optional selector, fallbackSelector, and stored fingerprint. Preserve returned Smart Match fingerprints rather than constructing a partial one. |
segment_ids | Comma-separated segment ID string, not an array. Every named segment must exist in this project's current configuration. Empty means the default audience. |
page | Comma-separated domain/path strings such as example.com/pricing, example.com/demo. Do not include a URL scheme. A bare domain uses * as its path; a leading slash uses any domain. |
content | String. Plain content replaces text. If every nonblank line has /find/replace/ form, the service creates find-and-replace entries. |
visibility | show or hide |
style | Object of style modifications |
attr | Object of attribute modifications |
add_classes, remove_classes | Comma-separated class-name strings |
New changes with the same ordered segment-ID list share a variant. Use the same segment ordering throughout a create request; differently ordered lists can create separate variants even when they name the same audience. Audience rules for new variants require all named segments. A new change with an omitted or null page applies to all domains and paths; its returned page string is */*.
Smart Match fingerprint schema
targeting.mode is required when a targeting object is stored. targeting.selector and targeting.fallbackSelector are strings. A targeting.fingerprint object requires text, which requires string content. Its optional matchType is exact, contains, or startsWith, defaulting to exact.
The remaining fingerprint sections are optional objects:
| Section | Child fields |
|---|---|
visual | fontSize with numeric min and max; fontWeight with numeric min; positionY with numeric min and max; boolean isAboveFold |
element | String tagName; string-array candidateTags, default [] |
structure | Integer siblingIndex, siblingCount, and depth; string parentChain |
semantics | Nullable strings id, ariaRole, and ariaLabel; nullable object dataAttributes; string-array meaningfulClasses, default [] |
content | Integer charCount and wordCount; string textPrefix |
These declarations do not impose a maximum fingerprint size or a numeric range on visual measurements. A returned fingerprint records a specific element. Reusing its fields unchanged preserves the stored targeting representation.
Updating changes without losing content
Omitting changes leaves every stored action untouched. Supplying it defines the new action list. Stored actions omitted from that list are removed, along with variants whose actions were all omitted. Variants that already had no actions are retained because the flat representation cannot name them.
For a retained action, send its returned id and variant_id. Omitted fields retain their stored values, and unchanged returned values preserve the original representation. Explicit null clears content, targeting, style, attributes, or classes; a null selector becomes an empty selector, a null segment_ids moves the action to the default audience, and a null page resets targeting to all pages. This does not make the whole changes list a patch.
A duplicate action ID, a mismatched variant ID, an ambiguous repeated legacy ID, or an unknown ID without new targeting can return 422 under errors.changes. Unknown segment references return 422 under the matching changes.N.segment_ids path. Do not retry a partial list as though it were an append operation.
Campaign response fields
The response includes id, name, is_active, base_url, testing, goal_ids, changes, and outcome when stored. Each change includes every key in the change table. Missing optional values serialize as null. The service generates cpn_ campaign IDs, variant IDs, and action IDs.
Deleting a campaign removes it from the draft. Publishing activates or removes the campaign on the website. Campaign testing settings are not the separate flow/question/offer A/B-test lifecycle.
Illustrative requests and responses
These illustrative examples use the fictional WorkForge project. The same resource schema covers every CRUD response.
The PATCH example also works with PUT. The create, item-read, and update envelopes have this shape. The list places these resource objects in its data array. An update returns the updated values. DELETE returns no JSON.