Overview

This page is a full reference for the REST API, including a list of all available endpoints. It also includes basic instructions on how to form requests and consume responses. Use the navigation on the left to find the documentation most relevant to you.

If you'd like a quick introduction to the REST API, refer to the Getting started guide.

If you have any questions, you can ask the developer community, or you can submit a ticket to the developer support team. We'll be happy to assist you.

Authentication

Every API request needs to be authenticated. To authenticate, you can generate an API token described in the Token based authentication section.

You can also use OAuth 2.0 to authenticate API calls. Please refer to OAuth 2.0 documentation.

Request Types

The endpoints below should be added on after the version in the API URL.

GET

GET requests retrieve an entity or list of entities. They are always read-only.

To get a single entity, use its id in the URL. To get a list of all entities, leave it off.

If the operation succeeds, the response will include the data in the body and a 200 OK response code.

POST

A POST requests creates an entity in Optimizely, relative to a certain parent (for example, an experiment within a project). The parent entity's id is provided in the URL, and the data for the entity being created is provided as JSON in the body.

If the operation succeeds, the response will include the created entity as JSON in the body, including a new id argument, and a 201 CREATED response code.

PUT

A PUT request updates an entity. The id for the entity to update is provided in the URL, and the new data is provided in the body as JSON. Only the data that you're changing needs to be provided. Missing fields will keep their original values.

If the operation succeeds, the response will include the data in the body and a 202 ACCEPTED response code.

DELETE

A DELETE request removes an entity. The id for the entity to delete is provided in the URL, and no data is sent in the body.

If the operation succeeds, the response will have a 204 NO CONTENT response code.

Response Codes

If you send a request and it succeeds, the response will include data in the JSON body and 200 OK (GET), 201 CREATED (POST), or 202 ACCEPTED (PUT), or 204 NO CONTENT (DELETE) as the HTTP response code.

If the request fails, we'll return one of the following error codes:

  • 400: Bad Request can happen if your request was not sent in valid JSON. It might help to specify a Content-Type: application/json header in your request. If you sent valid JSON, the error may also reference specific fields that were invalid.

  • 401 Unauthorized if your API token was missing or included in the body rather than the header.

  • 403 Forbidden if you provided an API token but it was invalid or revoked, or if you don't have read/write access to the entity you're trying to view/edit.

  • 404 Not Found if the id used in the request was inaccurate or you didn't have permission to view/edit it.

  • 429 Too Many Requests if you hit a rate limit for the API. If you receive this response, we recommend waiting at least 60 seconds before re-attempting the request.

  • 503 Service Unavailable if the API is overloaded or down for maintenance. If you receive this response, we recommend waiting at least 60 seconds before re-attempting the request.

Changes and Deprecation

This API is still relatively new, and we expect to add new resources and properties frequently. You should treat the data shown below as a subset of what might return in an API response.

For major changes to existing behavior, including removing functionality, we'll introduce a new version of the API and provide at least 3 months notice before deprecating an earlier version.

Change Log

  • August 24th, 2015: We've added the authorization code grant type with refresh tokens to our OAuth 2.0 support.
  • May 11th, 2015: You can now upload targeting lists via the REST API.
  • March 27th, 2015: You can now retrieve statistics computed by Optimizely Stats Engine via the API.
  • March 19th, 2015: We have added OAuth 2.0 support so third party applications can connect with the REST API on behalf of an Optimizely customer.
  • February 24th, 2015: You can now create and edit dimensions via the REST API.
  • February 23rd, 2015: Replace "Browser" condition type with "Browser / Version", "Device", and "Platform / OS" conditions. For more information see Audience Conditions. At this time "Browser" conditions are deprecated but will continue to work until further notice.
  • February 19th, 2015: You can now schedule experiments using the REST API.
  • September 26th, 2014: We have added an interactive mode to our REST API so you can test GET requests directly from the documentation.
  • September 10th, 2014: You can now get the results for experiments via the API.
  • July 31st, 2014: Audiences now have a segmentation property that Platinum customers can toggle. See the section on Audiences for more information.
  • July 30th, 2014: You can now create click and custom event goals via the API.
  • July 28th, 2014: You can now get a shareable link to an experiment's results page when you get read the experiment via the API.
  • July 22nd, 2014: You can now create and edit audiences using conditions via the API.
  • July 22nd, 2014: You can now edit overall traffic allocation by updating an experiment's percentage_included field.
  • July 18th, 2014: We fixed two known issues:
    • You can now create many variations on an experiment asynchronously. Previously, creating variations in parallel could cause them to become "detached" from the experiment.
    • You can once again update URL conditions for an experiment. This was temporarily unavailable.
  • June 30, 2014: Added "Known Issues" to the Experiment and Variation sections.
  • June 27, 2014: Added documentation on Goals

Projects

A project is a collection of experiments, goals, and audiences. Each project has an associated JavaScript file to include on the page.

Read a project

GET projects/1234/

Get metadata for a single project.

Definitions

project_name

The name of the project in Optimizely

project_status

Can be Active or Archived

account_id

The account the project is associated with

include_jquery

Either true or false. If set to true, the recommended version (1.11.3) will be used.

library

The prefered jQuery library you would like to use with your snippet. We support the following jquery-1.6.4-full, jquery-1.6.4-trim, jquery-1.11.3-full, and jquery-1.11.3-trim. If you do not want to include jQuery, set this field to none and include_jquery to false.

project_javascript

The JavaScript code which runs before Optimizely on all pages, regardless of whether or not there is a running experiment.

enable_force_variation

Set to true to enable the force variation parameter

exclude_disabled_experiments

Set to true to remove paused and draft experiments from the snippet

exclude_names

Set to true to mask descriptive names

ip_filtering

The same string that you'll find in Optimizely under Project Settings > IP Filtering, or null if it's not set.

socket_token

The token used to identify your mobile app to Optimizely

dcp_service_id

The ID of the Dynamic Customer Profile Service associated with this project.

Create a project

POST projects/

Create a new project in your account. The project_name is required in the request. The other editable arguments are all optional.

Update a project

PUT projects/1234

Editable fields

  • project_status
  • project_name
  • include_jquery
  • project_javascript
  • enable_force_variation
  • exclude_disabled_experiments
  • exclude_names
  • ip_anonymization
  • ip_filter
  • dcp_service_id

Delete a project

Deleting projects is not supported.

List projects in account

GET projects/

Get a list of all the projects in your account, with associated metadata.

Experiments

An A/B experiment is a set of rules for matching visitors to content and recording their conversions. Experiments are the hub that connect several other models:

  • Goals measure conversions and determine a winner.
  • Audiences determine which visitors will see an experiment.
  • Variations define the code that should be applied on a page to change the experience for a visitor, and the percentage of visitors who should see that code.

A multivariate experiment also has Sections. A section is a collection of variations that all manipulate the same feature of the page.

A multipage experiment adds Pages, which manipulate different URLs on your site.

Read an experiment

GET experiments/15/

Get metadata for a single experiment.

Definitions

id

The unique identifier for the experiment

project_id

The project the experiment was created in.

variation_ids

A list of variations in the experiment. A basic A/B test has two variations.

edit_url

The page that will show up in the Optimizely editor.

description

The name that will show up in the Optimizely dashboard and editor.

display_goal_order_lst

List of goal IDs representing the goals applicable to the experiment.

primary_goal_id

The ID of the primary goal for the experiment.

details

The description or hypothesis for an experiment.

custom_css

CSS which is applied to all the variations in the experiment, including the Original. Learn more here.

custom_js

JavaScript code which runs before variation code for all the variations in the experiment, including the Original. Learn more here.

status

A Running experiment will be live for visitors. A Paused or Not started experiment will not. Archived experiments will be hidden in Optimizely.

url_conditions

The pages where an experiment will run. For more details, see our article on URL Targeting. This property is now editable through the API. URL conditions are objects with these properties:

  • match_type: default is simple, can also be regex, exact, or substring

  • value: the URL string to match

  • negate: default is false, setting it to true will exclude the URL

percentage_included

The percentage of your visitors that should see the experiment, measured in basis points. 100 basis points = 1% traffic.

activation_mode

Can be immediate, manual or 'conditional', see Activation Mode.

conditional_code

The JavaScript condition or function used to activate the experiment. Learn more here.

experiment_type

A normal A/B test is ab but this could also be multivariate or multipage. See Experiment Type Overview.

shareable_results_link

A link that anyone can use to see your experiment's results, whether or not they're logged into Optimizely.

audience_ids

List of IDs of all audiences the experiment is targeted at.

Create a new experiment

POST projects/1234/experiments/

The project_id is required in the URL, and the description and edit_url are required in the body. The other editable arguments are all optional.

When you create an experiment, Optimizely will also fill in associated data by default. These defaults mimic the behavior of Optimizely's editor and include:

  • Two variations in variation_ids named "Original" and "Variation #1". The default variations have 50% traffic each and no code.
  • One URL targeting condition in url_conditions. By default, your experiment is targeted to the edit_url with a simple match.
  • Traffic allocated to 100% in percentage_included. Traffic is measured in basis points. Divide by 100 to get a percentage.
  • A status of "Not started", meaning the experiment will not be running initially.
  • Immediate activation_mode, rather than manual.
  • The experiment_type will be a normal A/B test, rather than a multivariate or multipage test.

Update an experiment

PUT experiments/15

Editable fields

  • audience_ids (add or remove an audience ID here to change the experiment's targeting)
  • activation_mode
  • description
  • edit_url
  • status (send "Running" to start an experiment and "Paused" to stop)
  • custom_css
  • custom_js
  • percentage_included
  • url_conditions

We don't currently support creating or updating multivariate or multipage tests via the API.

Delete an experiment

DELETE experiments/15

Sending DELETE on an experiment will permanently delete the experiment and its results.

In most cases, it's safer to archive the experiment by sending a PUT request with {"status": "Archived"}. This will remove the experiment from the Optimizely snippet and hide it in the project dashboard, but still leave it available under "Archived Experiments" for viewing and recovery later.

List experiments in project

GET projects/1234/experiments/

Get a list of all the experiments in a project.

Schedules

Experiments can be scheduled to start or stop at a particular time. A Schedule is a specification of a start time, stop time, or both, associated with a particular experiment. To learn more about scheduling experiments, see the Experiment Scheduler.

Read a schedule

GET schedules/1234

Get data about a particular schedule, including the start time and stop time of the associated experiment.

Definitions

status

Indicates whether this schedule is active for the experiment. Either ACTIVE or INACTIVE.

start_time

Start time of the scheduled experiment in UTC, or null.

stop_time

Stop time of the scheduled experiment in UTC, or null.

experiment_id

ID of the scheduled experiment.

id

ID of the schedule.

Create a schedule

POST experiments/1234/schedules

Create a schedule for an experiment. You must specify either a start_time or stop_time, or both. All times are in UTC and must be specified in the format 2015-01-01T08:00:00Z. The created schedule will always be marked ACTIVE, and any previously created schedules will be marked as INACTIVE.

Update a schedule

PUT schedules/1234

Update a schedule. You must specify either a start_time or stop_time, or both. All times are in UTC and must be specified in the format 2015-01-01T08:00:00Z.

Delete a schedule

DELETE schedules/1234

Permanently delete a schedule. If the schedule being deleted was marked as ACTIVE, the associated experiment will no longer be scheduled.

List schedules for experiment

GET experiments/1234/schedules

See a list containing the current schedule for an experiment as well as any previously created schedules. The current schedule will be marked ACTIVE and any previously created schedules will be marked INACTIVE.

Variations

Every experiment contains a set of variations that each change the visitor's experience in a different way. Variations define the code that should be applied on a page to change the experience, and the percentage of visitors who should see that code. A standard "A/B" test has two variations (including the original), and Optimizely supports adding many more variations.

Read a variation

GET variations/859611684

Get metadata for a single variation.

Definitions

is_paused

Default is false, true means no new visitors will see the variation

description

The name that shows up as a tab in the Optimizely editor

weight

The percentage of your visitors that should see this variation, measured in basis points. 100 basis points = 1% traffic. Variation weights should add up to 10000.

js_component

The JavaScript code that will run for a variation

Create a new variation

POST experiments/854484703/variations/

The experiment_id is required in the URL, and the description is required in the body. Most variations will also want to include js_component, but an Original can use the default value of an empty string.

Whenever possible, you should also include the correct weight and update the other variations so their weights sum to 10000.

Note that newly created experiments come with two variations created automatically, so you may need to PUT a variation rather than POSTing it.

Update a variation

PUT variations/859611685

The id is required in the URL.

Editable fields

  • description
  • is_paused (set this to true to stop the variation from getting traffic)
  • js_component
  • weight

Delete a variation

DELETE variations/859611685

Deleting a variation is the preferred way to remove it from an experiment. Directly editing the variation_ids property on experiments is not supported.

List variations in experiment

GET experiments/854484703/variations/

List all variations associated with the experiment.

Goals

Goals are the metrics used to decide which variation in an experiment is the winner. Like audiences, goals are defined at the project level and can be reused across multiple experiments within a project. Each goal is tracked for each experiment it's associated with. An experiment with no goals will still run, but its results page will be empty.

Read a goal

GET goals/543071054/

Optimizely has several different goal types, as explained in our knowledge base. Depending on the goal type, different fields in the response are important.

Common properties

All goals have a unique id and a title that shows up in the Optimizely editor and results page. They also have a goal_type with one of the following integer values:

  • 0 Click
  • 1 Custom event
  • 2 Engagement
  • 3 Pageviews
  • 4 Revenue

Pageview, click and custom event goals can be created via the API. Engagement and revenue goals are created automatically with each project and can be added or removed from experiments.

Goals can also be designated as addable, where true means they'll show up in the "Saved Goals" list for reuse across experiments and false means they'll be hidden from the list.

Goals with is_editable set to true can be updated using a PUT request. Old goals cannot be edited, and will have this field set to false.

Click goals

Click goals track clicks on any element matched by the jQuery selector.

If target_to_experiments is true, the goal will use the exact same targeting conditions as the experiment as a whole. If it's false, then the goal will be measured on the pages defined in target_urls according to target_url_match_types.

Pageview goals

Pageview goals track the number of visitors to the pages specified in urls, as specified by url_match_types.

The url_match_types can use the following integer values:

  • 1 Exact
  • 2 Regular expression
  • 3 Simple
  • 4 Substring

Custom event goals

Custom event goals allow you to capture and report on visitor actions or events that might not be related exclusively to clicks or page views. The event to track is defined in event.

Create a goal

POST projects/1234/goals/

For all goals, the title and goal_type are required. For each goal type, other fields are required:

  • Click goals need a selector and a boolean value for target_to_experiments to be set. If it's true, the goal will run on the same pages as the experiment it's it attached to. If it's false, you should also provide target_urls and target_url_match_types.
  • Pageview goals need a list of urls and url_match_types and will match nowhere if the lists are empty.
  • Custom event goals need an event name.

Add or remove a goal

To add a goal to an experiment, you'll need push that experiment's id onto the experiment_ids list.

To remove a goal, remove the experiment from the goal's experiment_ids list.

Update a goal

PUT goals/1234

Editable fields

  • archived
  • description
  • experiment_ids
  • goal_type
  • selector
  • target_to_experiments
  • target_urls
  • target_url_match_types
  • title
  • urls
  • url_match_types

Please note that old goals cannot be edited, and will have is_editable set to false.

Delete a goal

DELETE goals/1234

Delete a goal and remove it from all associated experiments. Deleting a goal will also remove it from past experiments, and you won't be able to see results for that goal on those experiments.

It's usually better to remove a goal from an experiment than delete it directly.

List goals in project

GET projects/1234/goals/

Get a list of all the goals in a project. The project_id in the URL is required.

Audiences

An Audience is a group of visitors that match set conditions. You can target an experiment to one or more audiences, or you can segment experiment results to see how different audiences performed. You can learn more about audiences in our knowledge base.

Read an audience

GET audiences/567/

Get metadata for a single audience.

Definitions

id

The unique identifier for the audience

project_id

The project the audience was created in

name

The name of the audience

description

A short description

conditions

A string defining the targeting rules for an audience. See the sections on audience conditions for more information.

segmentation

True if the audiences is available for segmentation on the results page (Platinum only).

archived

True if the audience has been archived

Create an audience

POST projects/1234/audiences/

The only required field in the request is name, and you can optionally add a description. The project_id is also required in the URL.

By default, the conditions field will just be an empty list []. In this case, the audience will not match anyone automatically. Instead, you can add visitors to it by id using the addToAudience function in our JavaScript API.

Platinum customers can also set the segmentation field. The default value is false, but you can set it to true to track the audience's behavior on the results page. See the section below on updating audiences for more information.

Update an audience

PUT audiences/568

Editable fields

Only Platinum customers can enable segmentation, and you can only enable segmentation on an audience if you have fewer than ten dimensions or other audiences enabled for segmentation. If you don't have sufficient permissions or already have 10 audiences/dimensions, the API will return an error.

Delete an audience

Deleting audiences is not supported.

List audiences in project

GET projects/758824777/audiences/

Get a list of all the audiences in a project. The project_id in the URL is required.

Uploaded lists

Uploaded Lists have been replaced by List Attributes. Please use the updated endpoints to create and manage lists. See our knowledge base for information on how to use lists in the Optimizely UI.

An uploaded list is a set of user identifiers that you have uploaded to Optimizely. Membership in a targeting list can be used to define an Optimizely audience, so you can target experiments only to a particular set of users.

We currently support three targeting list formats: cookies, query parameters and zip codes.

Uploaded lists are an Enterprise feature and may not be available for your Optimizely account. If you are uncertain whether you have access or would like to request access for development purposes, submit a ticket to the developer support team.

Read an uploaded list

GET targeting_lists/123/

Get metadata for a single uploaded list.

Definitions

name

A unique, human-readable name for the uploaded list

description

A brief description of the uploaded list

list_type

The type of uploaded list (1 = cookies, 2 = query parameters, 3 = zip codes)

key_fields

A comma-separated list of cookies (if list_type is 1) or query parameters (if list_type is 2) to target on

id

The unique identifier for the uploaded list

project_id

The unique identifier for the parent Optimizely project

account_id

The unique identifier for the parent Optimizely account

format

Format of the uploaded list (should always be a csv file)

Create an uploaded list

POST projects/456/targeting_lists/

Create an uploaded list with the given name and comma-separated set of values.

name must be unique across all lists defined in the current project, and can only contain characters, numbers, hyphens, and underscores.

list_type must take one of the following values:

  • 1 Cookie
  • 2 Query string
  • 3 Zip code

list_content should contain the content of the list in comma-separated format and format must be set to csv.

Currently we limit list size to 5 MB and row length to 100 characters. If you would like to upload a list larger than 5 MB, we recommended that you split it into several lists and then use "OR" conditions to target users who are in any of those lists.

All fields are required with the exception of description.

Update an uploaded list

PUT targeting_lists/123/

Overwrite the uploaded list with the provided id. Required arguments are identical to creating a new uploaded list.

Note that name and format cannot be modified.

Delete an uploaded list

DELETE targeting_lists/123/

Permanently deletes the given uploaded list.

List uploaded lists in project

GET projects/456/targeting_lists/

Show all of the uploaded lists that have been uploaded to a project.

Dimensions

Dimensions are attributes of visitors to your website or mobile app, such as demographic data, behavioral characteristics, or any other information particular to a visitor. Dimensions can be used to construct audiences and segment experiment results.

The REST API allows you to create, edit, or delete dimensions. If you want to track visitor data for a dimension you must use a client-side API (for websites, use the JavaScript API). To learn more about dimensions, see Dimensions: Capture visitor data through the API.

Read a dimension

GET dimensions/1234/

Get metadata for a single dimension.

Definitions

name

Name of the dimension.

last_modified

Time when the dimension was last modified, in UTC.

client_api_name

A unique name to refer to this dimension when tracking data in a client-side API call.

id

The unique identifier for the dimension.

description

A description of the dimension.

Create a dimension

POST projects/1234/dimensions

Create a new dimension with the specified name. The client_api_name and description fields are optional. If there is an existing dimension with a duplicate name or client_api_name the API will return a 400 error.

Update a dimension

PUT dimensions/1234

Update the name, client_api_name, or description of an existing dimension.

Delete a dimension

DELETE dimensions/1234

Permanently delete a dimension. By taking this action, any audiences using this dimension will stop getting traffic, and results associated with this dimension will be permanently deleted.

List dimensions in project

GET projects/1234/dimensions/

Get a list of all the custom dimensions in a project.

Results

Stats engine results

GET experiments/1234/stats

Use the /stats endpoint to get the top-level results of an experiment, computed using the Optimizely Stats Engine.

Stats Engine is only available for experiments started on or after January 21, 2015. For older experiments, you must use the /results endpoint. Those results will match what you see on the Optimizely results page.

The request requires an experiment_id and the response contains a list of JSON objects representing every combination of variations and goals that have been defined for that experiment. For example, if there are three variations and two goals defined for an experiment, the response will contain six JSON objects representing each variation_id and goal_id combination.

To filter results to visitors in a particular audience, add the optional audience_id parameter to the URL, e.g. ?audience_id=123.

To filter results to visitors with a particular custom dimension value, add the optional dimension_id and dimension_value parameters, e.g. ?dimension_id=456&dimension_value=foo.

The /stats endpoint may return a 503 error when it is overloaded. If you experience any issues submit a ticket to the developer support team.

Definitions

variation_id

ID of the variation. If the experiment is a multivariate test, this field is a list of variation IDs delimited by the underscore (_) character. (The field is a string rather than an integer to support this case.)

variation_name

Name of the variation. If the experiment is a multivariate test, this field is a list of variation names delimited by commas (,).

goal_id

ID of the goal.

goal_name

Name of the goal.

baseline_id

ID of the variation that is the baseline for this experiment.

begin_time

Begin time for the result dataset in UTC.

end_time

End time for the result dataset in UTC.

visitors

Number of visitors that were shown this variation.

conversions

Number of visitors that were shown this variation and converted to the specified goal.

conversion_rate

Conversion rate, computed as conversions/visitors. Only present if this is not a revenue goal.

status

Indicates whether a winner has been declared. Must take one of the values winner, loser, or inconclusive. For baseline variations, the value is always baseline.

improvement

Relative improvement over the baseline, computed as the ratio of conversion_rate values minus 1. For revenue goals, this is computed as the ratio of revenue_per_visitor values minus 1.

statistical_significance

The likelihood that the observed difference in conversion rates is not due to chance.

difference

The absolute difference in conversion rates from baseline. For revenue goals, the difference in revenue_per_visitor from baseline.

difference_confidence_interval_min

Lower value of the confidence interval for difference.

difference_confidence_interval_max

Upper value of the confidence interval for difference.

visitors_until_statistically_significant

Estimate for number of visitors required to reach statistical significance.

is_revenue

Boolean indicating if this a revenue goal.

revenue

Total revenue generated by this variation. Only present if this is a revenue goal.

revenue_per_visitor

Average revenue per visitor, computed as revenue/visitors. Only present if this is a revenue goal.

Legacy results

GET experiments/1234/results

Use the /results endpoint to get the top-level results of an experiment, computed using a traditional t-test.

Experiments started on or after January 21, 2015 also have statistics computed by Stats Engine. For consistency with the Optimizely results page, we recommend you use the /stats endpoint instead of the /results endpoint for those experiments.

The /results endpoint differs in several ways from the /stats endpoint. In particular, it returns a confidence field instead of statistical_significance, and the value is computed using a traditional t-test rather than Stats Engine. confidence represents the "Chance to Beat Baseline" that you may find on the results page for old experiments.

The request requires an experiment_id and the response contains a list of JSON objects representing every combination of variations and goals that have been defined for that experiment. For example, if there are three variations and two goals defined for an experiment, the response will contain six JSON objects representing each variation_id and goal_id combination.

To filter results to visitors in a particular audience, add the optional audience_id parameter to the URL, e.g. ?audience_id=123.

To filter results to visitors with a particular custom dimension value, add the optional dimension_id and dimension_value parameters, e.g. ?dimension_id=456&dimension_value=foo.

The /results endpoint may return a 503 error when it is overloaded. If you experience any issues submit a ticket to the developer support team.

Definitions

variation_id

ID of the variation. If the experiment is a multivariate test, this field is a list of variation IDs delimited by the underscore (_) character. (The field is a string rather than an integer to support this case.)

variation_name

Name of the variation. If the experiment is a multivariate test, this field is a list of variation names delimited by commas (,).

goal_id

ID of the goal.

goal_name

Name of the goal.

baseline_id

ID of the variation that is the baseline for this experiment.

begin_time

Begin time for the result dataset in UTC.

end_time

End time for the result dataset in UTC.

visitors

Number of visitors that were shown this variation.

conversions

Number of visitors that were shown this variation and converted to the specified goal.

conversion_rate

Conversion rate, computed as conversions/visitors. Only present if this is not a revenue goal.

status

Indicates whether a winner has been declared. Must take one of the values winner, loser, or inconclusive. For baseline variations, the value is always baseline.

difference

The absolute difference in conversion rates from baseline. For revenue goals, the difference in revenue_per_visitor from baseline.

improvement

Relative improvement over the baseline, computed as the ratio of conversion_rate values minus 1. For revenue goals, this is computed as the ratio of revenue_per_visitor values minus 1.

confidence

Chance to beat baseline.

is_revenue

Boolean indicating if this a revenue goal.

revenue

Total revenue generated by this variation. Only present if this is a revenue goal.

revenue_per_visitor

Average revenue per visitor, computed as revenue/visitors. Only present if this is a revenue goal.

DCP Services

A DCP Service provides all Customer Profile related services including storage, processing, and delivery. A DCP Service stores customer data in a set of tables (also known as datasources). A table stores a set of related customer attributes under a common ID space. For example, all customer attributes collected by your CRM may be stored in a "CRM" table; customer attributes from your data warehouse may be stored in a separate "Data Warehouse" table. Because the same customer will likely be identified using different IDs in different tables, a DCP Service also stores aliases (identity links) to reconcile attributes of the same customer across tables. In the figure below, because the customer identified by ANON_ID_1 in "My Data Warehouse" is the same customer identified by OEU_2 in "Optimizely Datasource", the Alias Table records this identity as a row.

Currently, each Optimizely Account can have a maximum of one DCP Service. Please submit a support ticket if you think you have a need for multiple DCP Services.

Associating Optimizely Projects to a DCP Service

Upon creation, a DCP Service is not linked to any projects. In order to build audiences which reference DCP data in a given project, you must link that project to a DCP Service using update project. Multiple Optimizely projects can be linked to a single DCP Service.

Uploading Data

To upload customer attributes from a particular source, add a table to your DCP Service. Each DCP Service contains a provisioned AWS account used for bulk data uploads. Details on uploading data to a table can be found here. You can upload customer attributes to a table in a streaming manner using the customer profile APIs or in bulk using the table's S3 bucket.

Read a DCP Service

GET dcp_services/567

Get metadata for a single DCP Service. The dcp_service_id is required in the URL.

Every DCP Service is provisioned with AWS credentials; you may use these credentials to upload data in bulk to a datasource specific S3 path

Definitions

account_id

Account ID that this DCP Service belongs to

archived

Boolean indicating whether this DCP Service is archived

aws_access_key

Access key for provisioned AWS account

aws_secret_key

Secret key for provisioned AWS account

created

Creation date of DCP Service

last_modified

Last modified date of DCP Service

name

The name of this DCP Service

s3_path

S3 path for the entire DCP Service

Create DCP Service

POST dcp_services

Create a new DCP Service under your account.

Required Fields

  • name
NOTE: The DCP Service is not yet linked to any projects. After creating a DCP Service, be sure to link a project to the DCP Service using update project.
NOTE: Currently, each Optimizely Account can have a maximum of one DCP Service. Please submit a support ticket if you think you have a need for multiple DCP Services.

Update DCP Service

PUT dcp_services/567

Update a single DCPService. The dcp_service_id is required in the URL.

Editable Fields

  • name

Delete a DCP Service

DELETE dcp_services/567

Delete a DCP Service. The dcp_service_id is required in the URL.

This archives all files in the corresponding AWS account.

List DCP Services

GET dcp_services

Get all DCP services for this account.

DCP Tables (Datasources)

Note: DCP Datasources are now referred to as "Tables" in the Optimizely Web UI. However, the REST API spec continues to use the word "Datasource". As a result, both terms will be present in developer docs

A table stores a set of related customer attributes under a common ID space.

A single DCP Service can have several tables. The figure above shows three tables: "My Data Warehouse", "Email Platform", "Optimizely Datasource", each with customer attributes obtained from a different source, and each with a different way to identify the same customer. For example, the customer identified by ANON_ID_2 in "My Data Warehouse" could be the same customer identified by OEU_1 in "Optimizely Datasource". Organizing customer data by table allows you to send data to Optimizely without requiring you to reconcile data across tables. This task of reconciling data of the same customer across tables can be achieved using the alias operation.

When creating a table, you will provide a customer ID locator (type and name), which tells Optimizely where we can find the customer ID on your web pages. When a customer visits, Optimizely will read their customer ID (for each table) and alias it to their Optimizely User ID. In the figure, the "Email Platform" table has a locator whose type is cookie and whose name is email_platform_cookie_name. In order for aliasing to work, you would have to place an appropriate customer ID (matching the customer ID for every row that you upload for this table) in a cookie named email_platform_cookie_name.

If you prefer to alias customer IDs manually, and if you know the corresponding Optimizely User ID for each of your customer IDs, you can do so using the alias API.

Read a Table

GET dcp_datasources/678

Get metadata for the specified Table (datasource). The dcp_datasource_id is required in the URL.

Definitions

id

Table ID (also known as dcp_datasource_id)

archived

Boolean indicating whether this DCP Service is archived

attributes

An array of all attributes inside this Table

aws_secret_key

Secret key for provisioned aws account

aws_access_key

Access key for provisioned aws account

created

Creation date of DCP Service

dcp_service_id

The DCPService this Table is associated with

description

A short description

is_optimizely

Boolean indicating if this is the Optimizely Datasource

keyfield_locator_type

Type of customer ID locator. Must be one of "cookie", "query parameter", "js_variable", or "uid".

keyfield_locator_name

Name of customer ID locator. Required for all keyfield_locator_types except "uid", and must match the regular expression /^[a-zA-Z_][a-zA-Z_0-9\$]*$/

last_modified

Last modified date of this Table

name

The name of the Table

s3_path

S3 path for this Table

Create a Table

POST dcp_services/567/dcp_datasources

Create a Table for the specified DCP Service. The dcp_service_id is required in the URL.

Required Fields

  • name
  • keyfield_locator_type: Must be one of
    • "cookie"
    • "query parameter"
    • "js_variable"
    • "uid"
  • keyfield_locator_name: Name of customer ID locator. Required for all keyfield_locator_types except "uid", and must match the regular expression /^[a-zA-Z_][a-zA-Z_0-9\$]*$/.

Update a Table

PUT dcp_datasources/678

Update a Table (datasource). The dcp_datasource_id is required in the URL.

Editable fields

  • name
  • description
  • keyfield_locator_type: Must be one of
    • "cookie"
    • "query parameter"
    • "js_variable"
    • "uid"
  • keyfield_locator_name: Name of customer ID locator. Required for all keyfield_locator_types except "uid", and must match the regular expression /^[a-zA-Z_][a-zA-Z_0-9\$]*$/.

Delete a Table

DELETE dcp_datasources/678

Delete a Table (datasource). The dcp_datasource_id is required in the URL.

List Tables

GET dcp_services/567/dcp_datasources

Get a list of all Tables in the specified DCP Service. The dcp_service_id is required in the URL.

DCP Attributes

A Table Attribute describes one aspect of a customer's profile within a Table. As shown in the figure below, your data warehouse might store a customer's "Lifetime Value", and "Loyalty Card" information, while your email platform might store if the customer "Opens Frequently". In DCP, attributes require a datatype, and some datatypes (e.g. datetime) require a format. Providing attribute datatypes and formats makes data validation and export to other databases feasible.

Use the Attributes APIs below to register and manage attribute metadata for a given Table, and the customer profile APIs to upload and update attribute values.

Read Attribute

GET dcp_datasource_attributes/789

Get metadata for the specified attribute. The attribute_id is required in the URL.

Definitions

archived

Whether the attribute is archived.

created

Creation date of the attribute.

datatype

Datatype of the attribute. Must be one of "string", "bool", "long", "double", "datetime".

dcp_datasource_id

ID of the Table (datasource) to which the attribute belongs.

description

Description of the attribute.

format

When datatype is date, must be one of "yyyy-mm-dd", "yyyy-mm-ddThh:mm:ssZ", "epoch".

is_value_public

Whether the attribute is "content-enabled".

last_modified

Last modified date of the attribute

name

Name of the attribute. Used to identify an attribute across our REST APIs and bulk upload. Note that this name is case-sensitive.

Create Attribute

POST dcp_datasources/678/dcp_datasource_attributes

Create a single attribute for customer profiles in a Table (datasource). The dcp_datasource_id is required in the URL.

Datatype options

  • "string"
  • "bool"
  • "long"
  • "double"
  • "datetime": Needs format to be a Datetime format

Datetime format options

  • "yyyy-mm-dd": ISO_8601 UTC date format
  • "yyyy-mm-ddThh:mm:ssZ": ISO_8601 datetime format
  • "epoch": Epoch time in milliseconds

Update Attribute

PUT dcp_datasource_attributes/789

Update a single attribute. The attribute_id is required in the URL.

Editable fields

  • description
NOTE: Updates to an attribute's name or datatype are not currently supported. We recommend archiving the existing attribute and creating a replacement, with the desired name, datatype, and format.

Delete Attribute

DELETE dcp_datasource_attributes/789

Archive a single attribute. The attribute_id is required in the URL.

Once an attribute is archived, you can no longer update or read Customer Profile data for this attribute. You can unarchive an attribute at any time.

List Attributes

GET dcp_datasources/678/dcp_datasource_attributes

Get a list of all attributes in the specified Table (datasource). The dcp_datasource_id is required in the URL.

DCP Customer Profiles

Customer Profiles are a collection of your customers' attributes across several Tables. The following APIs allow you to create, update, and read customer attributes for a single Table.

To use these APIs, we recommend that you first read the sections on DCP Services, Tables, and Attributes

Using the consolidated customer profile API call, you can retrieve the complete Customer Profile across all Tables.

The APIs that follow use the domain: https://vis.optimizely.com/api/

Read customer profile

GET customer_profile/567/678/oeu1234.5678

Get a single customer profile. The dcp_service_id, dcp_datasource_id, and customer_id_in_datasource are required in the URL.

Write customer profile

POST customer_profile/567/678/oeu1234.5678

Create or update a single customer profile. The dcp_service_id, dcp_datasource_id, and customer_id_in_datasource are required in the URL.

The request data must be a JSON object, where each key is the name of an attribute and each value must conform to the attribute's datatype and format.

Note:

  • The specified attribute value overwrites any existing value specified earlier.
  • The request may contain a subset of defined attributes.
  • If a key does not correspond to a registered attribute name, the write will fail
  • If a value does not respect the attribute's datatype/format, the write will fail

Read consolidated customer profile

GET consolidatedCustomerView/567/678/oeu1234.5678

Get a consolidated view of a single customer profile. The dcp_service_id, optimizely_datasource_id and optimizely_user_id are required in the URL.

The profile is consolidated by aliasing across different Tables in the DCP Service.

The datasourceId for this call should be the ID of the "Optimizely Datasource". You can find this ID using List Tables and finding the Table with is_optimizely=true. In this example, it is 678. The customerId for this call should be the Optimizely User ID. In this example, it is oeu1234.5678.

DCP Alias

Aliases are used to link each customer ID in your Tables to an Optimizely User ID. The Optimizely User ID is a random ID generated by Optimizely (stored in the optimizelyEndUserId cookie).

As shown in the figure, an alias indicates that the same customer is identified by ANON_ID_1 in "My Datasource" and by OEU_2 in the "Optimizely Datasource". This allows Optimizely to present a consolidated customer profile for that customer and allows you to target customers based on all of your Table Attributes.

These APIs that follow use the domain https://vis.optimizely.com/api/

Get Aliases

GET alias/567/678/oeu1234.5678

Get all customer IDs aliased to the specified Optimizely User ID. The dcp_service_id, optimizely_datasource_id, and optimizely_user_id are required in the URL.

The data section of the response is a map of datasource (Table) IDs to their corresponding Customer IDs, each aliased to the canonical Optimizely User ID.

The datasourceId for this call should be the ID of the "Optimizely Datasource". You can find this ID using List Tables and finding the Table with is_optimizely=true. In this example, it is 678. The customerId for this call should be the Optimizely User ID. In this example, it is oeu1234.5678.

Create Alias

POST alias/567/678/oeu1234.5678

Alias customer IDs to the specified Optimizely User ID. The dcp_service_id, optimizely_datasource_id, and optimizely_user_id are required in the URL.

In the example, the customer IDs corresponding to Tables 8905 and 1232 are now aliased to the Optimizely User ID oeu1234.5678. The "Optimizely Datasource" ID is 678 and the DCP Service ID is 567.

The datasourceId for this call should be the ID of the "Optimizely Datasource". You can find this ID using List Tables and finding the Table with is_optimizely=true. In this example, it is 678. The customerId for this call should be the Optimizely User ID. In this example, it is oeu1234.5678.

You do not need to use this API in order for aliases to be created. If you configure your Tables with appropriate customer ID locators, Optimizely will automatically alias your customer IDs to Optimizely User IDs (as customers visit your website).