Create a new audience
You can create a new audience by making a POST request to the /audiences
endpoint.
API format
POST /audiences
Request
A sample request for creating a Platform-generated audience
curl -X POST https://platform.adobe.io/data/core/ups/audiences
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"name": "People who ordered in the last 30 days",
"profileInstanceId": "AEPSegments",
"description": "Last 30 days",
"type": "SegmentDefinition",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "workAddress.country = \"US\""
},
"schema": {
"name": "_xdm.context.profile"
},
"labels": [
"core/C1"
]
}'
Property | Description |
---|---|
name | The name of the audience. |
description | A description of the audience. |
type | A field that displays whether the audience is Platform-generated or is an externally generated audience. Possible values include SegmentDefinition and ExternalSegment . A SegmentDefinition refers to an audience that was generated in Platform, while an ExternalSegment refers to an audience that was not generated in Platform. |
expression | The Profile Query Language (PQL) expression of the audience. More information about PQL expressions can be found in the PQL expressions guide. |
schema | The Experience Data Model (XDM) schema of the audience. |
labels | Object-level data usage and attribute-based access control labels that are relevant to the audience. |
Response
A successful response returns HTTP status 200 with information about your newly created audience.
A sample response when creating a Platform-generated audience.
{
"id": "60ccea95-1435-4180-97a5-58af4aa285ab",
"audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
"schema": {
"name": "_xdm.context.profile"
},
"profileInstanceId": "ups",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "6ed34f6f-fe21-4a30-934f-6ffe21fa3075",
"sandboxName": "prod",
"type": "production",
"default": true
},
"isSystem":false,
"name": "People who ordered in the last 30 days",
"description": "Last 30 days",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "workAddress.country = \"US\""
},
"mergePolicyId": "ef006bbe-750e-4e81-85f0-0c6902192dcc",
"evaluationInfo": {
"batch": {
"enabled": false
},
"continuous": {
"enabled": true
},
"synchronous": {
"enabled": false
}
},
"dataGovernancePolicy": {
"excludeOptOut": true
},
"creationTime": 1650374572000,
"updateEpoch": 1650374573,
"updateTime": 1650374573000,
"createEpoch": 1650374572,
"_etag": "\"33120d7c-0000-0200-0000-625eb7ad0000\"",
"dependents": [],
"definedOn": [
{
"meta:resourceType": "unions",
"meta:containerId": "tenant",
"$ref": "https://ns.adobe.com/xdm/context/profile__union"
}
],
"dependencies": [],
"type": "SegmentDefinition",
"originName": "REAL_TIME_CUSTOMER_PROFILE",
"overridePerformanceWarnings": false,
"createdBy": "{CREATED_BY_ID}",
"lifecycleState": "active",
"labels": [
"core/C1"
],
"namespace": "AEPSegments"
}
Look up a specified audience
You can look up detailed information about a specific audience by making a GET request to the /audiences
endpoint and providing the ID of the audience you wish to retrieve in the request path.
API format
GET /audiences/{AUDIENCE_ID}
Parameter | Description |
---|---|
{AUDIENCE_ID} | The ID of the audience you are trying to retrieve. Please note that this is the id field, and is not the audienceId field. |
Request
A sample request for retrieving an audience
curl -X GET https://platform.adobe.io/data/core/ups/audiences/60ccea95-1435-4180-97a5-58af4aa285ab \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns HTTP status 200 with information about the specified audience.
A sample response when retrieving a Platform-generated audience.
{
"id": "60ccea95-1435-4180-97a5-58af4aa285ab",
"audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
"schema": {
"name": "_xdm.context.profile"
},
"profileInstanceId": "ups",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "6ed34f6f-fe21-4a30-934f-6ffe21fa3075",
"sandboxName": "prod",
"type": "production",
"default": true
},
"isSystem": false,
"name": "People who ordered in the last 30 days",
"description": "Last 30 days",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "workAddress.country = \"US\""
},
"mergePolicyId": "ef006bbe-750e-4e81-85f0-0c6902192dcc",
"evaluationInfo": {
"batch": {
"enabled": false
},
"continuous": {
"enabled": true
},
"synchronous": {
"enabled": false
}
},
"dataGovernancePolicy": {
"excludeOptOut": true
},
"creationTime": 1650374572000,
"updateEpoch": 1650374573,
"updateTime": 1650374573000,
"createEpoch": 1650374572,
"_etag": "\"33120d7c-0000-0200-0000-625eb7ad0000\"",
"dependents": [],
"definedOn": [
{
"meta:resourceType": "unions",
"meta:containerId": "tenant",
"$ref": "https://ns.adobe.com/xdm/context/profile__union"
}
],
"dependencies": [],
"type": "SegmentDefinition",
"overridePerformanceWarnings": false,
"createdBy": "{CREATED_BY_ID}",
"lifecycleState": "active",
"labels": [
"core/C1"
],
"namespace": "AEPSegments"
}
Overwrite an audience
You can update (overwrite) a specific audience by making a PUT request to the /audiences
endpoint and providing the ID of the audience you wish to update in the request path.
API format
PUT /audiences/{AUDIENCE_ID}
Parameter | Description |
---|---|
{AUDIENCE_ID} | The ID of the audience that you want to update. Please note that this is the id field, and is not the audienceId field. |
Request
A sample request for updating an entire audience.
curl -X PUT https://platform.adobe.io/data/core/ups/audiences/4afe34ae-8c98-4513-8a1d-67ccaa54bc05 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"audienceId": "test-platform-audience-id",
"name": "New Platform audience",
"namespace": "AEPSegments",
"description": "Last 30 days",
"type": "SegmentDefinition",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "workAddress.country=\"US\""
}
"lifecycleState": "published",
"datasetId": "6254cf3c97f8e31b639fb14d",
"labels": [
"core/C1"
]
}'
Property | Description |
---|---|
audienceId | The ID of the audience. For externally generated audiences, this value may be supplied by the user. |
name | The name of the audience. |
namespace | The namespace for the audience. |
description | A description of the audience. |
type | A system-generated field that displays whether the audience is Platform-generated or is an externally generated audience. Possible values include SegmentDefinition and ExternalSegment . A SegmentDefinition refers to an audience that was generated in Experience Platform, while an ExternalSegment refers to an audience that was not generated in Experience Platform. |
expression | An object that contains the PQL expression of the audience. |
lifecycleState | The status of the audience. Possible values include draft , published , and inactive . draft represents when the audience is created, published when the audience is published, and inactive when the audience is no longer active. |
datasetId | The ID of the dataset that the audience data can be found. |
labels | Object-level data usage and attribute-based access control labels that are relevant to the audience. |
Response
A successful response returns HTTP status 200 with details of your newly updated audience. Please note that the details of your audience will differ depending if it is an Experience-Platform-generated audience or an externally generated audience.
A sample response when updating an entire audience.
{
"id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
"audienceId": "test-platform-audience-id",
"name": "New Experience Platform audience",
"namespace": "AEPSegments",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "6ed34f6f-fe21-4a30-934f-6ffe21fa3075",
"sandboxName": "prod",
"type": "production",
"default": true
},
"description": "Last 30 days",
"type": "SegmentDefinition",
"lifecycleState": "published",
"createdBy": "{CREATED_BY_ID}",
"datasetId": "6254cf3c97f8e31b639fb14d",
"_etag": "\"f4102699-0000-0200-0000-625cd61a0000\"",
"creationTime": 1650251290000,
"updateEpoch": 1650251290,
"updateTime": 1650251290000,
"createEpoch": 1650251290
}
Update an audience
You can update a specific audience by making a PATCH request to the /audiences
endpoint and providing the ID of the audience you wish to update in the request path.
API format
PATCH /audiences/{AUDIENCE_ID}
Parameter | Description |
---|---|
{AUDIENCE_ID} | The ID of the audience that you want to update. Please note that this is the id field, and is not the audienceId field. |
Request
A sample request for updating an audience.
curl -X PATCH https://platform.adobe.io/data/core/ups/audiences/60ccea95-1435-4180-97a5-58af4aa285ab5
-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}' \
-d '[
{
"op": "add",
"path": "/lifecycleState",
"value": "inactive"
}
]'
Property | Description |
---|---|
op | The type of PATCH operation performed. For this endpoint, this value is always /add . |
path | The path of the field to be updated. System-generated fields, such as id , audienceId , and namespace cannot be edited. |
value | The new value assigned to the property specified in path . |
Response
A successful response returns HTTP status 200 with the updated audience.
A sample response when patching a field in an audience.
{
"id": "60ccea95-1435-4180-97a5-58af4aa285ab5",
"audienceId": "test-platform-audience-id",
"name": "New Experience Platform audience",
"namespace": "AEPSegments",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "6ed34f6f-fe21-4a30-934f-6ffe21fa3075",
"sandboxName": "prod",
"type": "production",
"default": true
},
"description": "Last 30 days",
"type": "SegmentDefinition",
"lifecycleState": "inactive",
"createdBy": "{CREATED_BY_ID}",
"datasetId": "6254cf3c97f8e31b639fb14d",
"_etag": "\"f4102699-0000-0200-0000-625cd61a0000\"",
"creationTime": 1650251290000,
"updateEpoch": 1650251290,
"updateTime": 1650251290000,
"createEpoch": 1650251290
}
Delete an audience
You can delete a specific audience by making a DELETE request to the /audiences
endpoint and providing the ID of the audience you wish to delete in the request path.
API format
DELETE /audiences/{AUDIENCE_ID}
Parameter | Description |
---|---|
{AUDIENCE_ID} | The ID of the audience that you want to delete. Please note that this is the id field, and is not the audienceId field. |
Request
A sample request for deleting an audience.
curl -X DELETE https://platform.adobe.io/data/core/ups/audiences/60ccea95-1435-4180-97a5-58af4aa285ab5 \
-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 204 with no message.
Retrieve multiple audiences
You can retrieve multiple audiences by making a POST request to the /audiences/bulk-get
endpoint and providing the IDs of the audiences you wish to retrieve.
API format
POST /audiences/bulk-get
Request
A sample request for retrieving multiple audiences.
curl -X POST https://platform.adobe.io/data/core/ups/audiences/bulk-get
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d ' {
"ids": [
{
"id": "72c393ea-caed-441a-9eb6-5f66bb1bd6cd"
},
{
"id": "QU9fLTEzOTgzNTE0MzY0NzY0NDg5NzkyOTkx_6ed34f6f-fe21-4a30-934f-6ffe21fa3075"
}
]
}
Response
A successful response returns HTTP status 207 with information with your requested audiences.
A sample response when retrieving multiple audiences.
{
"results":{
"72c393ea-caed-441a-9eb6-5f66bb1bd6cd":{
"id": "72c393ea-caed-441a-9eb6-5f66bb1bd6cd",
"audienceId": "72c393ea-caed-441a-9eb6-5f66bb1bd6cd",
"schema": {
"name": "_xdm.context.profile"
},
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "6ed34f6f-fe21-4a30-934f-6ffe21fa3075",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "Sample audience",
"expression": {
"type": "pql",
"format": "pql/text",
"value": "_id = \"abc\""
},
"mergePolicyId": "87c94d51-239c-4391-932c-29c2412100e5",
"evaluationInfo": {
"batch": {
"enabled": false
},
"continuous": {
"enabled": true
},
"synchronous": {
"enabled": false
}
},
"ansibleUiEnabled": false,
"dataGovernancePolicy": {
"excludeOptOut": true
},
"creationTime": 1623889553000000,
"updateEpoch": 1674646369,
"updateTime": 1674646369000,
"createEpoch": 1623889552,
"_etag": "\"61030ec7-0000-0200-0000-63d113610000\"",
"dependents": [],
"definedOn": [
{
"meta:resourceType": "unions",
"meta:containerId": "tenant",
"$ref": "https://ns.adobe.com/xdm/context/profile__union"
}
],
"dependencies": [],
"type": "SegmentDefinition",
"state": "enabled",
"overridePerformanceWarnings": false,
"lastModifiedBy": "{CREATED_ID}",
"lifecycleState": "published",
"namespace": "AEPSegments",
"isSystem": false,
"saveSegmentMembership": true,
"originName": "REAL_TIME_CUSTOMER_PROFILE"
},
"QU9fLTEzOTgzNTE0MzY0NzY0NDg5NzkyOTkx_6ed34f6f-fe21-4a30-934f-6ffe21fa3075":{
"id": "QU9fLTEzOTgzNTE0MzY0NzY0NDg5NzkyOTkx_6ed34f6f-fe21-4a30-934f-6ffe21fa3075",
"name": "label test24764489707692",
"namespace": "AO",
"imsOrgId": "{ORG_ID}",
"sandbox":{
"sandboxId": "6ed34f6f-fe21-4a30-934f-6ffe21fa3075",
"sandboxName": "prod",
"type": "production",
"default": true
},
"type": "ExternalSegment",
"lifecycleState": "published",
"sourceId": "source-id",
"createdBy": "{USER_ID}",
"datasetId": "62bf31a105e9891b63525c92",
"_etag": "\"3100da6d-0000-0200-0000-62bf31a10000\"",
"creationTime": 1656697249000,
"updateEpoch": 1656697249,
"updateTime": 1656697249000,
"createEpoch": 1656697249,
"audienceId": "test-audience-id",
"isSystem": false,
"saveSegmentMembership": true,
"linkedAudienceRef": {
"aoWorkflowId": "62bf31858e87e34c8364befa"
},
"originName": "AUDIENCE_ORCHESTRATION"
}
}
}