Computed attributes API endpoint
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 list
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:
limit
limit=20
offset
offset=5
sortBy
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 name
, createEpoch
, mergeFunction.value
, updateEpoch
, and status
. The supported operations depend on the property listed.
name
:EQUAL
(=),NOT_EQUAL
(!=),CONTAINS
(=contains()),NOT_CONTAINS
(=!contains())createEpoch
:GREATER_THAN_OR_EQUALS
(<=),LESS_THAN_OR_EQUALS
(>=)mergeFunction.value
:EQUAL
(=),NOT_EQUAL
(!=),CONTAINS
(=contains()),NOT_CONTAINS
(=!contains())updateEpoch
:GREATER_THAN_OR_EQUALS
(<=),LESS_THAN_OR_EQUALS
(>=)status
:EQUAL
(=),NOT_EQUAL
(!=),CONTAINS
(=contains()),NOT_CONTAINS
(=!contains())
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.
code language-shell |
---|
|
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.
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
Property | Description |
_links |
An object that contains the pagination information required to access the last page of results, the next page of results, the previous page of results, or the current page of results. |
computedAttributes |
An array that contains the computed attributes based on your query parameters. More information about the computed attributes array can be found in the retrieve a specific computed attribute section. |
_page |
An object that contains metadata about the returned results. This includes information about the current offset, the count of computed attributes returned, the total count of computed attributes, as well as the limit of computed attributes returned. |
Create a computed attribute create
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
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 10-row-2 11-row-2 12-row-2 | |
---|---|
Property | Description |
name |
The name of the computed attribute field, as a string. The name of the computed attribute can only be comprised of alphanumeric characters without any spaces or underscores. This value must be unique amongst all the computed attributes. As a best practice, this name should be a camelCase version of the displayName . |
description |
A description of the computed attribute. This is especially useful once multiple computed attributes have been defined as it will help others within your organization to determine the correct computed attribute to use. |
displayName |
The display name for the computed attribute. This is the name that will be displayed when listing your computed attributes within the Adobe Experience Platform UI. |
expression |
An object that represents the query expression of the computed attribute you are trying to create. |
expression.type |
The type of the expression. Currently, only PQL is supported. |
expression.format |
The format of the expression. Currently, only pql/text is supported. |
expression.value |
The value of the expression. |
keepCurrent |
A boolean that determines whether or not the computed attribute’s value is kept up-to-date using fast refresh. Currently, this value should be set to false . |
duration |
An object that represents the lookback period for the computed attribute. The lookback period represents how far back can be looked back to compute the computed attribute. |
duration.count |
A number that represents the duration for the lookback period. The possible values depend on the value of the
|
duration.unit |
A string that represents the unit of time that will be used for the lookback period. Possible values include: HOURS , DAYS , WEEKS , and MONTHS . |
status |
The status of the computed attribute. Possible values include DRAFT and NEW . |
Response
A successful response returns HTTP status 200 with information about your newly created computed attribute.
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 | |
---|---|
Property | Description |
id |
The system-generated ID of your newly created computed attribute. |
status |
The computed attribute’s status. This can either be DRAFT or NEW . |
createEpoch |
The time at which the computed attribute was created, in seconds. |
updateEpoch |
The time at which the computed attribute was last updated, in seconds. |
createdBy |
The ID of the user who created the computed attribute. |
Retrieve a specific computed attribute get
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
code language-shell |
---|
|
Response
A successful response returns HTTP status 200 with detailed information about the specified computed attribute.
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 10-row-2 11-row-2 12-row-2 13-row-2 14-row-2 15-row-2 16-row-2 17-row-2 | |
---|---|
Property | Description |
id |
A unique, read-only, system-generated ID that can be used for referencing the computed attribute during other API operations. |
type |
A string that shows that the returned object is a computed attribute. |
name |
The name for the computed attribute. |
displayName |
The display name for the computed attribute. This is the name that will be displayed when listing your computed attributes within the Adobe Experience Platform UI. |
description |
A description of the computed attribute. This is especially useful once multiple computed attributes have been defined as it will help others within your organization to determine the correct computed attribute to use. |
imsOrgId |
The ID of the organization the computed attribute belongs to. |
sandbox |
The sandbox object contains details of the sandbox within which the computed attribute was configured. This information is drawn from the sandbox header sent in the request. For more information, please see the sandboxes overview. |
path |
The path to the computed attribute. |
keepCurrent |
A boolean that determines whether or not the computed attribute’s value is kept up-to-date using fast refresh. |
expression |
An object that contains the computed attribute’s expression. |
mergeFunction |
An object that contains the merge function for the computed attribute. This value is based off of the corresponding aggregation parameter within the computed attribute’s expression. Possible values include SUM , MIN , MAX , and MOST_RECENT . |
status |
The computed attribute’s status. This can be one of the following values: DRAFT , NEW , INITIALIZING , PROCESSING , PROCESSED , FAILED , or DISABLED . |
schema |
An object that contains information about the schema where the expression is evaluated in. Currently, only _xdm.context.profile is supported. |
lastEvaluationTs |
A timestamp that represents when the computed attribute was last evaluated. |
createEpoch |
The time at which the computed attribute was created, in seconds. |
updateEpoch |
The time at which the computed attribute was last updated, in seconds. |
createdBy |
The ID of the user who created the computed attribute. |
Delete a specific computed attribute delete
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
code language-shell |
---|
|
Response
A successful response returns HTTP status 202 with details of the deleted computed attribute.
code language-json |
---|
|
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
.
code language-shell |
---|
|
Response
A successful response returns HTTP status 200 with information about your newly updated computed attribute.
code language-json |
---|
|
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.