Computed attributes API endpoint
- Topics:
- Profiles
CREATED FOR:
- User
Computed attributes are functions used to aggregate event-level data into profile-level attributes. These functions are automatically computed so that they can be used across segmentation, activation, and personalization. This guide includes sample API calls for performing basic CRUD operations using the /attributes
endpoint.
To learn more about computed attributes, please begin by reading the computed attributes overview.
Getting started
The API endpoint used in this guide is part of the Real-Time Customer Profile API.
Before continuing, please review the Profile API getting started guide for links to recommended documentation, a guide to reading the sample API calls that appear in this document, and important information regarding required headers that are needed to successfully make calls to any Experience Platform API.
Additionally, please review the documentation for the following service:
- Experience Data Model (XDM) System: The standardized framework by which Experience Platform organizes customer experience data.
- Schema Registry getting started guide: Information about your
{TENANT_ID}
, which appears in responses throughout this guide, is provided.
- Schema Registry getting started guide: Information about your
Retrieve a list of computed attributes
You can retrieve a list of all the computed attributes for your organization by making a GET request to the /attributes
endpoint.
API format
The /attributes
endpoint supports several query parameters to help filter your results. While these parameters are optional, their use is strongly recommended to help reduce expensive overhead when listing resources. If you make a call to this endpoint with no parameters, all computed attributes available for your organization will be retrieved. Multiple parameters can be included, separated by ampersands (&
).
GET /attributes
GET /attributes?{QUERY_PARAMETERS}
The following query parameters can be used when retrieving a list of computed attributes:
Query parameter | Description | Example |
---|---|---|
limit | A parameter that specifies the maximum number of items returned as part of the response. The minimum value of this parameter is 1 and the maximum value is 40. If this parameter is not included, by default, 20 items will be returned. | limit=20 |
offset | A parameter that specifies the number of items to skip before returning the items. | offset=5 |
sortBy | A parameter that specifies the order in which the returned items are sorted. Available options include name , status , updateEpoch , and createEpoch . You can also choose whether to sort in ascending order or descending order by not including or including a - in front of the sort option. By default, the items will be sorted by updateEpoch in descending order. | sortBy=name |
property |
A parameter that lets you filter on various computed attribute fields. Supported properties include
| property=updateEpoch>=1683669114845 property=name!=testingrelease property=status=contains(new,processing,disabled) |
Request
The following request retrieves the last three computed attributes that were updated in your organization.
curl -X GET https://platform.adobe.io/data/core/ca/attributes?limit=3 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns HTTP status 200 with a list of the last 3 updated computed attributes that belong to your organization and sandbox.
{
"_links": {
"last": {
"href": "/attributes?offset=3&limit=1"
},
"next": {
"href": "/attributes?offset=20&limit=20"
},
"prev": {
"href": "/attributes?offset=0&limit=20"
},
"self": {
"href": "/attributes?offset=0&limit=20"
}
},
"computedAttributes": [
{
"id": "2e3bf98c-5840-4eb5-98c9-fcd7bde82188",
"type": "ComputedAttribute",
"name": "multipleFilterClauses19",
"displayName": "Multiple Filter Clauses 19",
"description": "Multiple Filter Clauses 19",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "e4f64b40-d8d9-11e9-a7ce-f3356ed0508b",
"sandboxName": "prod",
"type": "production",
"default": true
},
"path": "{TENANT_ID}/ComputedAttributes",
"keepCurrent": false,
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.checkouts.value > 0.0 or commerce.purchases.value > 1.0 or commerce.order.priceTotal >= 10.0)",
},
"mergeFunction": {
"value": "SUM"
},
"status": "DRAFT",
"schema": {
"name": "_xdm.context.profile"
},
"duration": {
"count": 7,
"unit": "DAYS"
},
"lastEvaluationTs": "",
"createEpoch": 1671223530322,
"updateEpoch": 1673043640946,
"createdBy": "{USER_ID}"
},
{
"id": "d9fbbd3d-049a-4561-b826-adc162511950",
"type": "ComputedAttribute",
"name": "multipleFilterClauses20",
"displayName": "Multiple Filter Clauses 20",
"description": "Multiple Filter Clauses 20",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "e4f64b40-d8d9-11e9-a7ce-f3356ed0508b",
"sandboxName": "prod",
"type": "production",
"default": true
},
"path": "{TENANT_ID}/ComputedAttributes",
"keepCurrent": true,
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[eventType.equals(\"commerce.backofficeOrderPlaced\", false)].topN(timestamp, 1).map({\"timestamp\": timestamp, \"value\": producedBy}).head()"
},
"mergeFunction": {
"value": "MOST_RECENT"
},
"status": "DRAFT",
"schema": {
"name": "_xdm.context.profile"
},
"duration": {
"count": 7,
"unit": "DAYS"
},
"lastEvaluationTs": "",
"createEpoch": 1671223586455,
"updateEpoch": 1671223586455,
"createdBy": "{USER_ID}"
},
{
"id": "afedff07-9d15-4385-b181-49708229d73b",
"type": "ComputedAttribute",
"name": "multipleFilterClauses18",
"displayName": "Multiple Filter Clauses 18",
"description": "Multiple Filter Clauses 18",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "e4f64b40-d8d9-11e9-a7ce-f3356ed0508b",
"sandboxName": "prod",
"type": "production",
"default": true
},
"path": "{TENANT_ID}/ComputedAttributes",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.checkouts.value > 0.0 or commerce.purchases.value > 1.0 or commerce.order.priceTotal >= 10.0)",
},
"mergeFunction": {
"value": "SUM"
},
"status": "PROCESSED",
"schema": {
"name": "_xdm.context.profile"
},
"duration": {
"count": 7,
"unit": "DAYS"
},
"lastEvaluationTs": "2023-08-27T00:14:55.028",
"createEpoch": 1671220358902,
"updateEpoch": 1671220358902,
"createdBy": "{USER_ID}"
}
],
"_page": {
"offset": 0,
"limit": 20,
"count": 3,
"totalCount": 3
}
}
_links
computedAttributes
_page
Create a computed attribute
To create a computed attribute, begin by making a POST request to the /attributes
endpoint with a request body containing the details of the computed attribute that you wish to create.
API format
POST /attributes
Request
curl -X POST https://platform.adobe.io/data/core/ca/attributes \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}'\
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "testing",
"displayName": "Sample Display Name",
"description": "Sample Description",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.checkouts.value > 0.0 or commerce.purchases.value > 1.0 or commerce.order.priceTotal >= 10.0)].sum(commerce.order.priceTotal)"
},
"keepCurrent": false,
"duration": {
"count": 4,
"unit": "DAYS"
},
"status": "DRAFT"
}'
name
displayName
.description
displayName
expression
expression.type
expression.format
pql/text
is supported.expression.value
keepCurrent
false
.duration
duration.count
A number that represents the duration for the lookback period. The possible values depend on the value of the duration.unit
field.
HOURS
: 1-24DAYS
: 1-7WEEKS
: 1-4MONTHS
: 1-6
duration.unit
HOURS
, DAYS
, WEEKS
, and MONTHS
.status
DRAFT
and NEW
.Response
A successful response returns HTTP status 200 with information about your newly created computed attribute.
{
"id": "1e8d0d77-b2bb-4b17-bbe6-2dbc08c1a631",
"type": "ComputedAttribute",
"name": "testing",
"displayName": "Sample Display Name",
"description": "Sample Description",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "02dd69f0-da73-11e9-9ea1-af59ce7c24e8",
"sandboxName": "prod",
"type": "production",
"isDefault": true
},
"path": "{TENANT_ID}/ComputedAttributes",
"keepCurrent": false,
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.checkouts.value > 0.0 or commerce.purchases.value > 1.0 or commerce.order.priceTotal >= 10.0)].sum(commerce.order.priceTotal)"
},
"mergeFunction": {
"value": "SUM"
},
"status": "DRAFT",
"schema": {
"name": "_xdm.context.profile"
},
"lastEvaluationTs": "",
"createEpoch": 1680070188696,
"updateEpoch": 1680070188696,
"createdBy": "{USER_ID}"
}
id
status
DRAFT
or NEW
.createEpoch
updateEpoch
createdBy
Retrieve a specific computed attribute
You can retrieve detailed information about a specific computed attribute by making a GET request to the /attributes
endpoint and providing the ID of the computed attribute you wish to retrieve in the request path.
API format
GET /attributes/{ATTRIBUTE_ID}
Request
curl -X GET 'https://platform.adobe.io/data/core/ca/attributes/1e8d0d77-b2bb-4b17-bbe6-2dbc08c1a631' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns HTTP status 200 with detailed information about the specified computed attribute.
{
"id": "1e8d0d77-b2bb-4b17-bbe6-2dbc08c1a631",
"type": "ComputedAttribute",
"name": "testing",
"displayName": "Sample Display Name",
"description": "Sample Description",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "02dd69f0-da73-11e9-9ea1-af59ce7c24e8",
"sandboxName": "prod",
"type": "production",
"isDefault": true
},
"path": "{TENANT_ID}/ComputedAttributes",
"keepCurrent": false,
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.checkouts.value > 0.0 or commerce.purchases.value > 1.0 or commerce.order.priceTotal >= 10.0) and (timestamp occurs <= 7 days before now)].sum(commerce.order.priceTotal)"
},
"mergeFunction": {
"value": "SUM"
},
"status": "DRAFT",
"schema": {
"name": "_xdm.context.profile"
},
"lastEvaluationTs": "",
"createEpoch": 1680070188696,
"updateEpoch": 1680070188696,
"createdBy": "{USER_ID}"
}
id
type
name
displayName
description
imsOrgId
sandbox
path
path
to the computed attribute.keepCurrent
expression
mergeFunction
SUM
, MIN
, MAX
, and MOST_RECENT
.status
DRAFT
, NEW
, INITIALIZING
, PROCESSING
, PROCESSED
, FAILED
, or DISABLED
.schema
_xdm.context.profile
is supported.lastEvaluationTs
createEpoch
updateEpoch
createdBy
Delete a specific computed attribute
You can delete a specific computed attribute by making a DELETE request to the /attributes
endpoint and providing the ID of the computed attribute you wish to delete in the request path.
DRAFT
). This endpoint cannot be used to delete computed attributes in any other state.API format
DELETE /attributes/{ATTRIBUTE_ID}
{ATTRIBUTE_ID}
id
value of the computed attribute you want to delete.Request
curl -X DELETE https://platform.adobe.io/data/core/ca/attributes/1e8d0d77-b2bb-4b17-bbe6-2dbc08c1a631 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns HTTP status 202 with details of the deleted computed attribute.
{
"id": "03ae581b-5f7b-48da-a9eb-4ef0daf4bc3c",
"type": "ComputedAttribute",
"name": "testdemopd2",
"displayName": "testdemopd2",
"description": "testdemopd2",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "02dd69f0-da73-11e9-9ea1-af59ce7c24e8",
"sandboxName": "prod",
"type": "production",
"isDefault": true
},
"path": "{TENANT_ID}/ComputedAttributes",
"keepCurrent": false,
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.shipping.shipDate occurs <= 1 days before now) and (timestamp occurs <= 1 days before now)].min(commerce.shipping.shipDate)"
},
"mergeFunction": {
"value": "MIN"
},
"status": "DRAFT",
"schema": {
"name": "_xdm.context.profile"
},
"lastEvaluationTs": "",
"createEpoch": 1681365690928,
"updateEpoch": 1681365690928,
"createdBy": "{USER_ID}"
}
Update a specific computed attribute
You can update a specific computed attribute by making a PATCH request to the /attributes
endpoint and providing the ID of the computed attribute you wish to update in the request path.
- If the current status is
NEW
, the status can only be changed toDISABLED
. - If the current status is
DRAFT
, you can change the values of the following fields:name
,description
,keepCurrent
,expression
, andduration
. You can also change the status fromDRAFT
toNEW
. Any changes to system-generated fields, such asmergeFunction
orpath
will return an error. - If the current status is either
PROCESSING
orPROCESSED
, the status can only be changed toDISABLED
.
API format
PATCH /attributes/{ATTRIBUTE_ID}
{ATTRIBUTE_ID}
id
value of the computed attribute you want to update.Request
The following request will update the status of the computed attribute from DRAFT
to NEW
.
curl -X PATCH https://platform.adobe.io/data/core/ca/attributes/1e8d0d77-b2bb-4b17-bbe6-2dbc08c1a631 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '
{
"description": "Sample Description",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.checkouts.value > 0.0 or commerce.purchases.value > 1.0 or commerce.order.priceTotal >= 10.0) and (timestamp occurs <= 7 days before now)].sum(commerce.order.priceTotal)"
},
"status": "NEW"
}'
Response
A successful response returns HTTP status 200 with information about your newly updated computed attribute.
{
"id": "1e8d0d77-b2bb-4b17-bbe6-2dbc08c1a631",
"type": "ComputedAttribute",
"name": "testing123",
"displayName": "Sample Display Name",
"description": "Sample Description",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "02dd69f0-da73-11e9-9ea1-af59ce7c24e8",
"sandboxName": "prod",
"type": "production",
"isDefault": true
},
"path": "{TENANT_ID}/ComputedAttributes",
"keepCurrent": false,
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.checkouts.value > 0.0 or commerce.purchases.value > 1.0 or commerce.order.priceTotal >= 10.0) and (timestamp occurs <= 7 days before now)].sum(commerce.order.priceTotal)"
},
"mergeFunction": {
"value": "SUM"
},
"status": "NEW",
"schema": {
"name": "_xdm.context.profile"
},
"lastEvaluationTs": "",
"createEpoch": 1680071726825,
"updateEpoch": 1680074429192,
"createdBy": "{USER_ID}"
}
Next steps
Now that you have learned the basics of computed attributes, you are ready to begin defining them for your organization. To learn how to use computed attributes in the Experience Platform UI, please read the computed attributes UI guide.