Dynamic Customer Profile Service (DCP)
This topic describes the REST API of Dynamic Customer Profile Service.
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.
![DCP_Service.png 910](https://files.readme.io/bb11d0f-DCP_Service.png)
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
Key | Value description |
---|---|
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
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.
![Datasource.png 910](https://files.readme.io/b6b7b46-Datasource.png)
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
Key | Value description |
---|---|
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 Experimentation 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
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 allkeyfield_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 allkeyfield_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.
![attributes.png 910](https://files.readme.io/97adeaf-attributes.png)
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
Key | Value description |
---|---|
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
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.
![customer_profiles.png 910](https://files.readme.io/80d8751-customer_profiles.png)
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).
![alias.png 910](https://files.readme.io/141d9bf-alias.png)
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"
Updated 1 day ago