Incisively DOCS back to main site

Suggestions

Request a variant from a lab.

Request

GET https://bandits.incisive.ly/v1/accounts/{account_id}/labs/{lab_id}/suggest

Parameters

key description
user A unique identifier for this user/visitor (we recommend generating a GUID and storing it in a cookie or similar – see ‘Notes’.)
s optional The segment ID for which to cluster this user into. Can be any string. Try to keep buckets large enough that it will have enough users to optimize over however.
ignore optional A comma seperated (no spaces) list of variant names which will not be suggested. Useful for excluding specific variants for spefic users.
f optional Force a specific variant, can still be rewarded.

Example

curl https://bandits.incisive.ly/v1/accounts/123456/labs/3f52e932-788c-43de-8a15-a1dce0f37cfd/suggest?user=ef20abb2-06db-45ad-9a5b-64705e207a80

Response

A JSON object detailing the suggestion with the following fields:

key description
content The Variant content that you should use in your application.
reward_token A special value that is unique to this User/Lab. You must store this value, since you’ll use it to signal a goal later

You will also find experiment_id and variant_id fields in the response, but these should not be used and may be removed in the future.

Example

Let’s say our Lab contains 3 variants with content red.jpg, blue.jpg and black.jpg respectively. A suggestion response body might look like this:

{
    "variant_id": "5baf1002-de62-4d63-5e61-f2c3582d563f",
    "reward_token": "pHZguhe-PwMA3w==",
    "content": "red.jpg",
    "experiment_id":"76610513-3418-4075-4e96-56db5a8cf9ee"
}

Notes

  • It is critical that you never cache or re-use any response from this API under any circumstances. This is a realtime service, and you should often expect different responses for the same request.

  • The endpoint URL includes a Lab ID, which can be found by clicking ‘Edit Lab’ in the web app.

  • We recommend creating a separate lab for use in dev/staging/test environments, to avoid affecting the optimisation process.

  • The user parameter is required to ensure repeat users always receive the same variant, and don’t skew the optimisation process. Any value that uniquely (and preferably anonymously) identifies the user will work, but for web applications we recommend creating a new permanent cookie with a random UUID. For mobile applications, the device ID is a good choice. Don’t use values that could change (like email address).

  • If you are integrating with Incisively on the server side, we strongly recommend you prevent robots and crawlers from triggering suggestions.

On Reward Tokens:

Reward tokens are unique to the user and lab, so ensure that you can store many per user in order to support multiple Labs. Again, permanent cookies are a good choice for web applications. A suggestion for the same Lab and User will always have the same reward_token, so you don’t need to worry about keeping it in sync. If the user has already rewarded the Lab, the field won’t be present.