Introduction

Welcome to the LeadPages Split Test API documentation. You can use this API to create and run split tests.

This API adheres to the LeadPages HTTP API Standards document, which is available on GitHub.

We suggest starting with the Walkthrough to begin accessing the API.

Endpoints

/splittest/v2

Split testing API version 2. The following high-level objects are available in this API.

Tests

/splittest/v2/tests

Tests group configuration and variations to form a split test.

Request

GET /splittest/v2/tests

Enumerate all tests.

Body
Empty

Query string
`cursor`	`String?` A string representing where a previous request "left off".
`limit`	`Regexp?(\d+)` The maximum number of items to return in the response.
`expand`	`Enum('true', 'True', 'yes', 'false', 'False', 'no')` A boolean for whether nested entities should be expanded.

Response

Body
`_items`	`List[Test]`
`_meta`	`ListingMeta` Meta information about the response.

Responses
`200 OK`

Errors
`400 Bad Request`	`failed to parse JSON request`
`400 Bad Request`	`bad content type`
`400 Bad Request`	`missing Content-Type header`
`400 Bad Request`	`unknown message`

Request

POST /splittest/v2/tests

Create a new test.

Body
`status`	`Enum('ready', 'foundry_pending', 'active', 'paused', 'completed', 'archived')` Whether the test is running, paused, etc. Only active tests trigger redirection. Defaults to `ready`.
`kind`	`Enum('split', 'multivariate')`
`winnerStatus`	`Enum('pending', 'setting', 'declared')` If the test is still waiting for a winner or has a found or declared winner.
`name`	`String?` Name of the test.
`control`	`String?` UUID of variation which is the control for this test.
`winner`	`String?` UUID of variation which is the winner for this test.
`assetKind`	`Enum('leadpage', 'leadbox')`
`slug`	`String?` The test's slug. If not set, the slug is generated from the name.

Response

Body
`status`	`Enum('ready', 'foundry_pending', 'active', 'paused', 'completed', 'archived')` Whether the test is running, paused, etc. Only active tests trigger redirection. Defaults to `ready`.
`kind`	`Enum('split', 'multivariate')`
`name`	`String?` Name of the test.
`control`	`String?` UUID of variation which is the control for this test.
`variations`	`List?[Variation]` List of variations belonging to the Split Test.
`winner`	`String?` UUID of variation which is the winner for this test.
`winnerStatus`	`Enum('pending', 'setting', 'declared')` If the test is still waiting for a winner or has a found or declared winner.
`isRedirected`	`Boolean?`
`slug`	`String?` The test's slug. If not set, the slug is generated from the name.
`_meta`	`Meta` Meta information about the resource.

Responses
`200 OK`

Errors
`400 Bad Request`	`unknown message`
`400 Bad Request`	`missing Content-Type header`
`400 Bad Request`	`bad content type`
`400 Bad Request`	`failed to parse JSON request`
`409 Conflict`	`unknown message`
`502 Bad Gateway`	`unknown message`

Test

/splittest/v2/tests/{uuid}

Request

GET /splittest/v2/tests/{uuid}

View a test.

Body
Empty

Query string
`expand`	`Enum('true', 'True', 'yes', 'false', 'False', 'no')` A boolean for whether nested entities should be expanded.

Response

Body
`status`	`Enum('ready', 'foundry_pending', 'active', 'paused', 'completed', 'archived')` Whether the test is running, paused, etc. Only active tests trigger redirection. Defaults to `ready`.
`kind`	`Enum('split', 'multivariate')`
`name`	`String?` Name of the test.
`control`	`String?` UUID of variation which is the control for this test.
`variations`	`List?[Variation]` List of variations belonging to the Split Test.
`winner`	`String?` UUID of variation which is the winner for this test.
`winnerStatus`	`Enum('pending', 'setting', 'declared')` If the test is still waiting for a winner or has a found or declared winner.
`isRedirected`	`Boolean?`
`slug`	`String?` The test's slug. If not set, the slug is generated from the name.
`_meta`	`Meta` Meta information about the resource.

Responses
`200 OK`

Errors
`400 Bad Request`	`failed to parse JSON request`
`400 Bad Request`	`bad content type`
`400 Bad Request`	`missing Content-Type header`
`404 Not Found`	`unknown message`
`502 Bad Gateway`	`unknown message`

Request

PATCH /splittest/v2/tests/{uuid}

Update a test.

Body
`status`	`Enum('ready', 'foundry_pending', 'active', 'paused', 'completed', 'archived')` Whether the test is running, paused, etc. Only active tests trigger redirection. Defaults to `ready`.
`kind`	`Enum('split', 'multivariate')`
`name`	`String?` Name of the test.
`control`	`String?` UUID of variation which is the control for this test.
`winner`	`String?` UUID of variation which is the winner for this test.
`winnerStatus`	`Enum('pending', 'setting', 'declared')` If the test is still waiting for a winner or has a found or declared winner.
`slug`	`String?` The test's slug. If not set, the slug is generated from the name.

Response

Body
`status`	`Enum('ready', 'foundry_pending', 'active', 'paused', 'completed', 'archived')` Whether the test is running, paused, etc. Only active tests trigger redirection. Defaults to `ready`.
`kind`	`Enum('split', 'multivariate')`
`name`	`String?` Name of the test.
`control`	`String?` UUID of variation which is the control for this test.
`variations`	`List?[Variation]` List of variations belonging to the Split Test.
`winner`	`String?` UUID of variation which is the winner for this test.
`winnerStatus`	`Enum('pending', 'setting', 'declared')` If the test is still waiting for a winner or has a found or declared winner.
`isRedirected`	`Boolean?`
`slug`	`String?` The test's slug. If not set, the slug is generated from the name.
`_meta`	`Meta` Meta information about the resource.

Responses
`200 OK`

Errors
`400 Bad Request`	`missing Content-Type header`
`400 Bad Request`	`bad content type`
`400 Bad Request`	`unknown message`
`400 Bad Request`	`failed to parse JSON request`
`404 Not Found`	`unknown message`
`409 Conflict`	`unknown message`
`502 Bad Gateway`	`unknown message`

Request

DELETE /splittest/v2/tests/{uuid}

Delete a test.

Body
Empty

Response

Body
Empty

Responses
`204 No Content`

Errors
`400 Bad Request`	`failed to parse JSON request`
`400 Bad Request`	`bad content type`
`400 Bad Request`	`missing Content-Type header`
`404 Not Found`	`unknown message`
`502 Bad Gateway`	`unknown message`

Stats

/splittest/v2/tests/{uuid}/stats

Request

PUT /splittest/v2/tests/{uuid}/stats

Compute win probability statistics.

Body
`variationData`	`List[VariationAnalyticsData]`

Response

Body
`action`	`Or[KeepTestingAction, StopTestingAction, RemoveVariationsAction, UseWinnerAction]`
`variationStats`	`List[VariationStats]`

Responses
`200 OK`

Errors
`400 Bad Request`	`failed to parse JSON request`
`400 Bad Request`	`bad content type`
`400 Bad Request`	`unknown message`
`400 Bad Request`	`missing Content-Type header`
`404 Not Found`	`unknown message`

Request

DELETE /splittest/v2/tests/{uuid}/stats

Clear cached win probability statistics.

Body
Empty

Response

Body
Empty

Responses
`204 No Content`

Errors
`400 Bad Request`	`failed to parse JSON request`
`400 Bad Request`	`bad content type`
`400 Bad Request`	`missing Content-Type header`
`404 Not Found`	`unknown message`

Variations

/splittest/v2/tests/{uuid}/variations

Request

GET /splittest/v2/tests/{uuid}/variations

Enumerate a test's variations.

Body
Empty

Query string
`cursor`	`String?` A string representing where a previous request "left off".
`limit`	`Regexp?(\d+)` The maximum number of items to return in the response.

Response

Body
`_items`	`List[Variation]`
`_meta`	`ListingMeta` Meta information about the response.

Responses
`200 OK`

Errors
`400 Bad Request`	`failed to parse JSON request`
`400 Bad Request`	`missing Content-Type header`
`400 Bad Request`	`bad content type`
`400 Bad Request`	`unknown message`
`404 Not Found`	`unknown message`

Request

POST /splittest/v2/tests/{uuid}/variations

Create a new variation for this test.

Body
`control`	`Boolean?`
`assetId`	`String` UUID of asset being tracked
`name`	`String`
`weight`	`Number(0 < n)` Weight of the variation relative to the other variations participating in the test. Ex. weights of 1.0 and 1.0 represent a 50/50 distribution.
`contentUuid`	`String?` Foundry content UUID of the asset being tracked. Marked optional to support pages but must be provided for a Leadbox.
`uri`	`URI?` URI the Variation represents.
`publicationDomain`	`String?`
`assetType`	`Enum('box', 'page')` Type of asset being tracked

Response

Body
`control`	`Boolean?`
`assetId`	`String?`
`name`	`String`
`weight`	`Number(0 < n)` Weight of the variation relative to the other variations participating in the test. Ex. weights of 1.0 and 1.0 represent a 50/50 distribution.
`contentUuid`	`String?` Foundry content UUID of the asset being tracked. Marked optional to support pages but must be provided for a Leadbox.
`winner`	`Boolean?`
`uri`	`URI?` URI the Variation represents.
`publicationDomain`	`String?`
`assetType`	`String?`
`_meta`	`Meta` Meta information about the resource.

Responses
`200 OK`

Errors
`400 Bad Request`	`missing Content-Type header`
`400 Bad Request`	`bad content type`
`400 Bad Request`	`unknown message`
`400 Bad Request`	`failed to parse JSON request`
`404 Not Found`	`unknown message`
`409 Conflict`	`too much contention over these entities, try again later`

Variations

/splittest/v2/variations

Variations represent one possible outcome of visiting the page that matches the split URI ("original") and being redirected. Generally, once a user has visited a given variation, they should only ever see that variation again.

Variations are always associated with a single test, and one variation is always the control. The control shares its outcome payload (a URI) with the test itself, to reflect that the control page is always the original page being tested against.

Request

GET /splittest/v2/variations

Enumerate variations.

Body
Empty

Query string
`cursor`	`String?` A string representing where a previous request "left off".
`limit`	`Regexp?(\d+)` The maximum number of items to return in the response.

Response

Body
`_items`	`List[Variation]`
`_meta`	`ListingMeta` Meta information about the response.

Responses
`200 OK`

Errors
`400 Bad Request`	`failed to parse JSON request`
`400 Bad Request`	`bad content type`
`400 Bad Request`	`missing Content-Type header`

Request

PATCH /splittest/v2/variations

Batch update variation weights.

Body
`test`	`String`
`weights`	`List[UpdateWeight]`

Response

Body
Empty

Responses
`200 OK`

Errors
`400 Bad Request`	`missing Content-Type header`
`400 Bad Request`	`bad content type`
`400 Bad Request`	`unknown message`
`400 Bad Request`	`failed to parse JSON request`
`404 Not Found`	`unknown message`
`409 Conflict`	`unknown message`
`409 Conflict`	`too much contention over these entities, try again later`
`502 Bad Gateway`	`unknown message`

Variation

/splittest/v2/variations/{uuid}

Request

GET /splittest/v2/variations/{uuid}

Get a variation.

Body
Empty

Response

Body
`control`	`Boolean?`
`assetId`	`String?`
`name`	`String`
`weight`	`Number(0 < n)` Weight of the variation relative to the other variations participating in the test. Ex. weights of 1.0 and 1.0 represent a 50/50 distribution.
`contentUuid`	`String?` Foundry content UUID of the asset being tracked. Marked optional to support pages but must be provided for a Leadbox.
`winner`	`Boolean?`
`uri`	`URI?` URI the Variation represents.
`publicationDomain`	`String?`
`assetType`	`String?`
`_meta`	`Meta` Meta information about the resource.

Responses
`200 OK`

Errors
`400 Bad Request`	`failed to parse JSON request`
`400 Bad Request`	`bad content type`
`400 Bad Request`	`missing Content-Type header`
`404 Not Found`	`unknown message`

Request

PATCH /splittest/v2/variations/{uuid}

Update a variation.

Body
`control`	`Boolean?`
`assetId`	`String?` UUID of asset being tracked
`name`	`String?`
`weight`	`Number?(0 < n)` Weight of the variation relative to the other variations participating in the test. Ex. weights of 1.0 and 1.0 represent a 50/50 distribution.
`contentUuid`	`String?` Foundry content UUID of the asset being tracked. Marked optional to support pages but must be provided for a Leadbox.
`winner`	`Boolean?`
`uri`	`URI?` URI the Variation represents.
`publicationDomain`	`String?`
`assetType`	`Enum('box', 'page')` Type of asset being tracked

Query string
`redirect`	`Enum('true', 'True', 'yes', '1', 'on', 'false', 'False', 'no', '0', 'off')`

Response

Body
`control`	`Boolean?`
`assetId`	`String?`
`name`	`String`
`weight`	`Number(0 < n)` Weight of the variation relative to the other variations participating in the test. Ex. weights of 1.0 and 1.0 represent a 50/50 distribution.
`contentUuid`	`String?` Foundry content UUID of the asset being tracked. Marked optional to support pages but must be provided for a Leadbox.
`winner`	`Boolean?`
`uri`	`URI?` URI the Variation represents.
`publicationDomain`	`String?`
`assetType`	`String?`
`_meta`	`Meta` Meta information about the resource.

Responses
`200 OK`

Errors
`400 Bad Request`	`missing Content-Type header`
`400 Bad Request`	`bad content type`
`400 Bad Request`	`unknown message`
`400 Bad Request`	`failed to parse JSON request`
`404 Not Found`	`unknown message`
`409 Conflict`	`unknown message`
`409 Conflict`	`too much contention over these entities, try again later`
`502 Bad Gateway`	`unknown message`

Request

DELETE /splittest/v2/variations/{uuid}

Delete a variation.

Body
Empty

Response

Body
Empty

Responses
`204 No Content`

Errors
`400 Bad Request`	`missing Content-Type header`
`400 Bad Request`	`bad content type`
`400 Bad Request`	`failed to parse JSON request`
`404 Not Found`	`unknown message`
`409 Conflict`	`unknown message`
`502 Bad Gateway`	`unknown message`

Ping

/splittest/v2/ping

Hearbeat endpoint. This is a standardized endpoint that responds according to LeadPages API conventions.

Request

GET /splittest/v2/ping

Perform heartbeat check.

Body
Empty

Response

Body
`_meta._version`	`String` The current internal version number of the API.
`_meta`	`Dictionary`

Responses
`200 OK`

Errors
Empty

Definitions

VariationAnalyticsData

VariationAnalyticsData
`conversions`	`Integer`
`variationId`	`String`
`uniqueViews`	`Integer`

KeepTestingAction

KeepTestingAction
`recommendation`	`Enum('keep_testing')`

StopTestingAction

StopTestingAction
`recommendation`	`Enum('stop_testing')`

RemoveVariationsAction

RemoveVariationsAction
`variationIds`	`List[String]`
`recommendation`	`Enum('remove_variations')`

UseWinnerAction

UseWinnerAction
`conversionLift`	`Number?(0.0 < n < 100.0)` Expected gain in conversion rate achieved by using the recommended variation
`variationId`	`String`
`winProbability`	`Number?(0.0 < n < 1.0)`
`recommendation`	`Enum('use_winner')`

VariationStats

VariationStats
`lossMagnitude`	`Number?(0.0 < n < 1.0)`
`variationId`	`String`
`winProbability`	`Number?(0.0 < n < 1.0)`

Variation

Variation
`control`	`Boolean?`
`assetId`	`String?`
`name`	`String`
`weight`	`Number(0 < n)` Weight of the variation relative to the other variations participating in the test. Ex. weights of 1.0 and 1.0 represent a 50/50 distribution.
`contentUuid`	`String?` Foundry content UUID of the asset being tracked. Marked optional to support pages but must be provided for a Leadbox.
`winner`	`Boolean?`
`uri`	`URI?` URI the Variation represents.
`publicationDomain`	`String?`
`assetType`	`String?`
`_meta`	`Meta` Meta information about the resource.

ListingMeta

ListingMeta
`count`	`Integer` The total number of items in the response.
`cursor`	`String?` This is used in conjunction with limit to paginate through lists of items.
`total`	`Integer?` The number of items in the database.
`limit`	`Integer` The requested limit on the number of items.

Test

Test
`status`	`Enum('ready', 'foundry_pending', 'active', 'paused', 'completed', 'archived')` Whether the test is running, paused, etc. Only active tests trigger redirection. Defaults to `ready`.
`kind`	`Enum('split', 'multivariate')`
`name`	`String?` Name of the test.
`control`	`String?` UUID of variation which is the control for this test.
`variations`	`List?[Variation]` List of variations belonging to the Split Test.
`winner`	`String?` UUID of variation which is the winner for this test.
`winnerStatus`	`Enum('pending', 'setting', 'declared')` If the test is still waiting for a winner or has a found or declared winner.
`isRedirected`	`Boolean?`
`slug`	`String?` The test's slug. If not set, the slug is generated from the name.
`_meta`	`Meta` Meta information about the resource.

UpdateWeight

UpdateWeight
`id`	`String`
`weight`	`Number(0 < n)` Weight of the variation relative to the other variations participating in the test. Ex. weights of 1.0 and 1.0 represent a 50/50 distribution.

Implementation Notes

Creating a Test

Tests group several variations together and provide other metdata about the test. A test may be in several states; to support various use cases, a test may be in a draft state (ready) or archived (archived), for example. By default, new tests are marked ready.

When adding a variation to a test, a few constraints apply. You may only have one control per test though there is no practical limit on how many variations you can have.

A placeholder test type is given (multivariate) but it is unused at this time.

Running a test

While a test is running, page views will be routed to the variations on the test according to weighted random choice, meaning that as the number of visitors increases, the actual traffic distribution will get statistically closer and closer to what was set up in the test.

As a way to optimize the page view distribution, the "weight" of a variation is only relevant as a proportion to the other variations in the test. Understandably, this may seem silly. A client or UI is very likely to just use a scale of 0-100% to set up traffic distribution, but treating the weighting in this way prevents having to update all variations on a test in certain cases in a way that makes it worthwhile to retain this behavior.

Completing (winning) a test

Tests can be completed in a number of ways:

The user may decide to end the test without regard to what variation won
The user may decide to declare a certain variation the winner
The system may elect to declare a variation the winner after some threshold is passed

At this time, only the first two scenarios are supported.

One can declare a winner by updating a particular variation (see the documentation for PATCHing a variation) to set the winner flag on it to true. This has the side effect of marking two properties on the parent test of that variation; its status will change to completed and its winnerStatus will change from pending to declared. The winnerStatus value of found is reserved for the third (unsupported) use case. Naturally, only one winner can be declared per test.

At this time you cannot "undeclare" a winner.

Meta
`updated`	`DateTime` When the resource was last updated.
`created`	`DateTime` When the resource was created.
`id`	`String` The resource's unique identifier.
`uri`	`String` The resource's absolute URI.