A Dynamic Customer Profile (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.

🚧

Important

Currently, each Optimizely Experimentation Account can have a maximum of one DCP Service. Contact Optimizely Support if you think you have a need for multiple DCP Services.

Associate Optimizely Experimentation projects to a DCP service

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

Upload data

To upload customer attributes from a particular source, create 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 Customer Profiles. You can upload customer attributes to a table using the API or in bulk using the table's S3 bucket.

Read a DCP service

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

GET dcp_services/567

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

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  "https://www.optimizelyapis.com/experiment/v1/dcp_services/567"

Example response

{
  "id": 567,
  "account_id": 123456,
  "archived": false,
  "aws_access_key": "123423asfakedf12vh451234",
  "aws_secret_key": "1234fake12341asdfas234zc",
  "created": "2015-08-01T11:50:37.864010Z",
  "last_modified": "2015-08-18T21:38:55.927670Z",
  "name": "My DCP Service",
  "s3_path": "dcp/567"
}

Response definitions

Create DCP service

Create a new DCP Service under your account.

POST dcp_services

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.
• Currently, each Optimizely Experimentation Account can have a maximum of one DCP Service. Contact Optimizely Support if you think you have a need for multiple DCP Services.

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  -H "Content-Type: application/json" \
  -d '{"name":"My DCP Service"}' \
  "https://www.optimizelyapis.com/experiment/v1/dcp_services"

Example response

{
  "id": 567,
  "account_id": 123456,
  "archived": false,
  "aws_access_key": "123423asfakedf12vh451234",
  "aws_secret_key": "1234fake12341asdfas234zc",
  "created": "2015-08-01T11:50:37.864010Z",
  "last_modified": "2015-08-18T21:38:55.927670Z",
  "name": "My DCP Service",
  "s3_path": "dcp/567"
}

Update DCP service

Update a single DCP service. The dcp_service_id is required in the URL.

PUT dcp_services/567

Editable fields

• name

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Awesome DCP Service"}' \
  "https://www.optimizelyapis.com/experiment/v1/dcp_services/567"

Example response

{
  "id": 567,
  "account_id": 123456,
  "archived": false,
  "aws_access_key": "123423asfakedf12vh451234",
  "aws_secret_key": "1234fake12341asdfas234zc",
  "created": "2015-08-01T11:50:37.864010Z",
  "last_modified": "2015-08-18T21:38:55.927670Z",
  "name": "My Awesome DCP Service",
  "s3_path": "dcp/567"
}

Delete DCP service

Delete a DCP Service. The dcp_service_id is required in the URL. This archives all files in the corresponding AWS account.

DELETE dcp_services/567

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  "https://www.optimizelyapis.com/experiment/v1/dcp_services/567"

List DCP services

Get all DCP services for this account.

GET dcp_services

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  "https://www.optimizelyapis.com/experiment/v1/dcp_services"

Example response

[
  {
    "id": 567,
    "account_id": 123456,
    "archived": false,
    "aws_access_key": "123423asfakedf12vh451234",
    "aws_secret_key": "1234fake12341asdfas234zc",
    "created": "2015-08-01T11:50:37.864010Z",
    "last_modified": "2015-08-18T21:38:55.927670Z",
    "name": "My DCP Service",
    "s3_path": "dcp/567"
  }
]

DCP tables (datasources)

📘

Note

DCP Datasources are now referred to as "Tables" in the Optimizely Web Experimentation 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 Experimentation 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 operations.

When creating a table, you will provide a customer ID locator (type and name), which tells Optimizely Web Experimentation where we can find the customer ID on your web pages. When a customer visits, Optimizely Web Experimentation 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 Web Experimentation User ID for each of your customer IDs, you can do so using the alias API.

Read a table

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

GET dcp_datasources/678

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  "https://www.optimizelyapis.com/experiment/v1/dcp_datasources/678"

Example response

{
  "id": 678,
  "archived": false,
  "attributes": [],
  "aws_access_key": "AKfakekeyV8SH8XTJBUPO",
  "aws_secret_key": "ailb234vK/fakekeyc8SH8SeGCh2leiuX",
  "created": "2015-08-20T23:26:08.414110Z",
  "dcp_service_id": 567,
  "description": "First party data from my Data Warehouse",
  "is_optimizely": false,
  "keyfield_locator_name": "_my_hashedEmailcookie",
  "keyfield_locator_type": "cookie",
  "last_modified": "2015-08-20T23:26:08.414140Z",
  "name": "My Data Warehouse",
  "s3_path": "dcp/567/678"
}

Response definitions

Create a table

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

POST dcp_services/567/dcp_datasources

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 mustmatch the regular expression /^[a-zA-Z_][a-zA-Z_0-9\$]*$/.

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Data Warehouse","keyfield_locator_type":"cookie","keyfield_locator_name":"_my_hashedEmailcookie"}' \
  "https://www.optimizelyapis.com/experiment/v1/dcp_services/567/dcp_datasources"

Example response

{
  "id": 678,
  "archived": false,
  "attributes": [],
  "aws_access_key": "AKfakekeyV8SH8XTJBUPO",
  "aws_secret_key": "ailb234vK/fakekeyc8SH8SeGCh2leiuX",
  "created": "2015-08-20T23:26:08.414110Z",
  "dcp_service_id": 567,
  "description": null,
  "is_optimizely": false,
  "keyfield_locator_name": "_my_hashedEmailcookie",
  "keyfield_locator_type": "cookie",
  "last_modified": "2015-08-20T23:26:08.414140Z",
  "name": "My Data Warehouse",
  "s3_path": "dcp/567/678"
}

Update a table

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

PUT dcp_datasources/678

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 mustmatch the regular expression /^[a-zA-Z_][a-zA-Z_0-9\$]*$/.

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Awesome Data Warehouse","keyfield_locator_type":"cookie","keyfield_locator_name":"_my_hashedEmailcookie"}' \
  "https://www.optimizelyapis.com/experiment/v1/dcp_datasources/678"

Example response

{
  "id": 678,
  "archived": false,
  "attributes": [],
  "aws_access_key": "AKfakekeyV8SH8XTJBUPO",
  "aws_secret_key": "ailb234vK/fakekeyc8SH8SeGCh2leiuX",
  "created": "2015-08-20T23:26:08.414110Z",
  "dcp_service_id": 567,
  "description": null,
  "is_optimizely": false,
  "keyfield_locator_name": "_my_hashedEmailcookie",
  "keyfield_locator_type": "cookie",
  "last_modified": "2015-08-20T23:26:08.414140Z",
  "name": "My Awesome Data Warehouse",
  "s3_path": "dcp/567/678"
}

Delete a table

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

DELETE dcp_datasources/678

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  "https://www.optimizelyapis.com/experiment/v1/dcp_datasources/678"

List tables

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

GET dcp_services/567/dcp_datasources

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  "https://www.optimizelyapis.com/experiment/v1/dcp_services/567/dcp_datasources"

Example response

[
  {
    "id": 789,
    "archived": false,
    "attributes": [],
    "aws_access_key": "AKfakekeyV8SH8XTJBUPO",
    "aws_secret_key": "ailb234vK/fakekeyc8SH8SeGCh2leiuX",
    "created": "2015-08-26T09:50:38.886990Z",
    "description": "Optimizely datasource",
    "dcp_service_id": 567,
    "is_optimizely": true,
    "keyfield_locator_name": null,
    "keyfield_locator_type": "uid",
    "last_modified": "2015-08-26T09:50:39.202950Z",
    "name": "Optimizely",
    "s3_path": "dcp/567/789"
  },
  {
    "id": 678,
    "archived": false,
    "attributes": [{
      "archived": false,
      "datatype": "long",
      "description": "Predicted LTV, per growth team",
      "format": null,
      "id": 111,
      "is_value_public": false,
      "name": "Life-time value"
    }, {
      "archived": false,
      "datatype": "long",
      "description": "Alexa rank",
      "format": null,
      "id": 222,
      "is_value_public": false,
      "name": "alexa_rank"
    }],
    "aws_access_key": "AKfakekeyV8SH8XTJBUPO",
    "aws_secret_key": "ailb234vK/fakekeyc8SH8SeGCh2leiuX",
    "created": "2015-08-20T23:26:08.414110Z",
    "dcp_service_id": 567,
    "description": "First party data from my Data Warehouse",
    "is_optimizely": false,
    "keyfield_locator_name": "_my_hashedEmailcookie",
    "keyfield_locator_type": "cookie",
    "last_modified": "2015-08-20T23:26:08.414140Z",
    "name": "My Awesome Data Warehouse",
    "s3_path": "dcp/567/678"
  }
]

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 metadata for the specified attribute. The attribute_id is required in the URL.

GET dcp_datasource_attributes/789

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  "https://www.optimizelyapis.com/experiment/v1/dcp_datasource_attributes/789"

Example response

{
  "archived": false,
  "created": "2015-08-18T21:38:55.927670Z",
  "datatype": "long",
  "dcp_datasource_id": 678,
  "description": "Predicted LTV, per growth team",
  "format": null,
  "id": 789,
  "is_value_public": false,
  "last_modified": "2015-08-18T21:38:55.927680Z",
  "name": "Life-time value"
}

Response definitions

Create attribute

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

POST dcp_datasources/678/dcp_datasource_attributes

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

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  -H "Content-Type: application/json" \
  -d '{"name":"Life-time value","datatype":"long","description":"Predicted LTV, per growth team"}' \
  "https://www.optimizelyapis.com/experiment/v1/dcp_datasources/678/dcp_datasource_attributes"

Example response

{
  "archived": false,
  "created": "2015-08-18T21:38:55.927670Z",
  "datatype": "long",
  "dcp_datasource_id": 678,
  "description": "Predicted LTV, per growth team",
  "format": null,
  "id": 789,
  "is_value_public": false,
  "last_modified": "2015-08-18T21:38:55.927680Z",
  "name": "Life-time value"
}

Update attribute

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

PUT dcp_datasource_attributes/789

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.

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  -H "Content-Type: application/json" \
  -d '{"name":"is_high_value_customer","datatype":"long"}' \
  "https://www.optimizelyapis.com/experiment/v1/dcp_datasource_attributes/789"

Example response

{
  "archived": false,
  "created": "2015-08-18T21:38:55.927670Z",
  "datatype": "long",
  "dcp_datasource_id": 678,
  "description": null,
  "format": null,
  "id": 789,
  "is_value_public": false,
  "last_modified": "2015-08-18T21:38:55.927680Z",
  "name": "is_high_value_customer"
}

Delete attribute

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.

DELETE dcp_datasource_attributes/789

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  "https://www.optimizelyapis.com/experiment/v1/dcp_datasource_attributes/789"

List attributes

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

GET dcp_datasources/678/dcp_datasource_attributes

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  "https://www.optimizelyapis.com/experiment/v1/dcp_datasources/678/dcp_datasource_attributes"

Example response

[
  {
    "archived": false,
    "datatype": "long",
    "dcp_datasource_id": 678,
    "description": "Predicted LTV, per growth team",
    "format": null,
    "id": 789,
    "is_value_public": false,
    "name": "Life-time value"
  },
  {
    "archived": false,
    "datatype": "string",
    "dcp_datasource_id": 678,
    "description": null,
    "format": null,
    "id": 790,
    "is_value_public": true,
    "name": "most_viewed_category"
  }
]

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 a single customer profile. The dcp_service_id, dcp_datasource_id, and customer_id_in_datasource are required in the URL.

GET customer_profile/567/678/oeu1234.5678

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  "https://vis.optimizely.com/api/customer_profile/567/678/oeu1234.5678"

Example response

{
  "data": {
    "Life-time value": 10,
    "most_viewed_category": "jeans"
  },
  "dcpServiceId": "567",
  "datasourceId": "678",
  "customerId": "oeu1234.5678"
}

Write customer profile

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.

POST customer_profile/567/678/oeu1234.5678

📘

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.

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  -H "Content-Type: application/json" \
  -d '{"data":{"Life-time value":10,"most_viewed_category":"jeans"}}' \
  "https://vis.optimizely.com/api/customer_profile/567/678/oeu1234.5678"

Example response

201 Created (empty response body)

Read consolidated customer profile

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.

GET consolidatedCustomerView/567/678/oeu1234.5678

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  "https://vis.optimizely.com/api/consolidatedCustomerView/567/678/oeu1234.5678"

Example response

[
  {
    "dcpServiceId": "567",
    "datasourceId": "789",
    "customerId": "oeu1234.5678",
    "data": {
      "Life-time value": 10,
      "most_viewed_category": "jeans"
    }
  },
  {
    "dcpServiceId": "567",
    "datasourceId": "790",
    "customerId": "sfdc1223a3_ji$ddd",
    "data": {
      "mrr": 10000
    }
  }
]

DCP alias

Aliases are used to link each customer ID in your Tables to anOptimizely User ID. The Optimizely User ID is a random ID generated by Optimizely Web Experimentation (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 Web Experimentation 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 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.

GET alias/567/678/oeu1234.5678

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  "https://vis.optimizely.com/api/alias/567/678/oeu1234.5678"

Example response

{
 "dcpServiceId": "567",
 "datasourceId": "678",
 "customerId": "oeu1234.5678",
 "data": {
   "8905": "sfdc1223a3_ji$ddd",
   "1232": "mkto1245433:213ad"
 }
}

Create alias

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.

POST alias/567/678/oeu1234.5678

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 Web Experimentation will automatically alias your customer IDs to Optimizely User IDs (as customers visit your website).

Example request

curl \
  -H "Token: abcdefghijklmnopqrstuvwxyz:123456" \
  -H "Content-Type: application/json" \
  -d '{"data":{"1232":"mkto1245433:213ad","8905":"sfdc1223a3_ji$ddd"}}' \
  "https://vis.optimizely.com/api/alias/567/678/oeu1234.5678"