Audiences endpoint
An audience is a collection of people who share similar behaviors and/or characteristics. These collections of people can be generated either by using Adobe Experience Platform or from external sources. You can use the /audiences
endpoint in the Segmentation API, which allows you to programmatically retrieve, create, update, and delete audiences.
Getting started
The endpoints used in this guide are part of the Adobe Experience Platform Segmentation Service API. Before continuing, please review the getting started guide for important information that you need to know in order to successfully make calls to the API, including required headers and how to read example API calls.
Retrieve a list of audiences list
You can retrieve a list of all audiences for your organization by making a GET request to the /audiences
endpoint.
API format
The /audiences
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 audiences available for your organization will be retrieved. Multiple parameters can be included, separated by ampersands (&
).
GET /audiences
GET /audiences?{QUERY_PARAMETERS}
The following query parameters can be used when retrieving a list of audiences:
start
start=5
limit
limit=10
sort
attributeName:[desc/asc]
.sort=updateTime:desc
property
property=
property=audienceId==test-audience-id
name
name=Sample
description
description=Test Description
Request
The following request retrieves the last two audiences created in your organization.
code language-shell |
---|
|
Response
A successful response returns HTTP status 200 with a list of audiences that were created in your organization as JSON.
code language-json |
---|
|
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3 9-row-3 10-row-3 11-row-3 12-row-3 13-row-3 14-row-3 15-row-3 16-row-3 17-row-3 18-row-3 | ||
---|---|---|
Property | Audience type | Description |
id |
Both | A system-generated read-only identifier for the audience. |
audienceId |
Both | If the audience is a Platform-generated audience, this is the same value as the id . If the audience is externally generated, this value is provided by the client. |
schema |
Both | The Experience Data Model (XDM) schema of the audience. |
imsOrgId |
Both | The ID of the organization that the audience belongs to. |
sandbox |
Both | Information about the sandbox that the audience belongs to. More information about sandboxes can be found in the sandboxes overview. |
name |
Both | The name of the audience. |
description |
Both | A description of the audience. |
expression |
Platform-generated | The Profile Query Language (PQL) expression of the audience. More information about PQL expressions can be found in the PQL expressions guide. |
mergePolicyId |
Platform-generated | The ID of the merge policy that the audience is associated with. More information about merge policies can be found in the merge policies guide. |
evaluationInfo |
Platform-generated | Shows how the audience will be evaluated. Possible evaluation methods include batch, synchronous (streaming), or continuous (edge). More information about the evaluation methods can be found in the segmentation overview |
dependents |
Both | An array of audience IDs that depend on the current audience. This would be used if you are creating an audience that is a segment of a segment. |
dependencies |
Both | An array of audience IDs that the audience depends on. This would be used if you are creating an audience that is a segment of a segment. |
type |
Both | 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 Platform, while an ExternalSegment refers to an audience that was not generated in Platform. |
originName |
Both | A field that refers to the name of the audience’s origin. For Platform-generated audiences, this value will be REAL_TIME_CUSTOMER_PROFILE . For audiences generated in Audience Orchestration, this value will be AUDIENCE_ORCHESTRATION . For audiences generated in Adobe Audience Manager, this value will be AUDIENCE_MANAGER . For other externally generated audiences, this value will be CUSTOM_UPLOAD . |
createdBy |
Both | The ID of the user who created the audience. |
labels |
Both | Object-level data usage and attribute-based access control labels that are relevant to the audience. |
namespace |
Both | The namespace that the audience belongs to. Possible values include AAM , AAMSegments , AAMTraits , and AEPSegments . |
linkedAudienceRef |
Both | An object that contains identifiers to other audience-related systems. |
Create a new audience create
You can create a new audience by making a POST request to the /audiences
endpoint.
API format
POST /audiences
Request
accordion | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
A sample request for creating a Platform-generated audience | ||||||||||||||||||||
|
accordion | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
A sample request for creating an externally generated audience | ||||||||||||||||||||||||||||
|
Response
A successful response returns HTTP status 200 with information about your newly created audience.
accordion | ||
---|---|---|
A sample response when retrieving a Platform-generated audience. | ||
|
accordion | ||
---|---|---|
A sample response when retrieving an externally generated audience. | ||
|
Update a field in an audience update-field
You can update the fields of 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}
{AUDIENCE_ID}
id
field, and is not the audienceId
field.Request
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
Property | Description |
op |
For updating audiences, this value is always add . |
path |
The path of the field you want to update. |
value |
The value that you want to update the field to. |
Response
A successful response returns HTTP status 200 with information about your newly updated audience.
code language-json |
---|
|
Update an audience put
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}
{AUDIENCE_ID}
id
field, and is not the audienceId
field.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 | |
---|---|
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 Platform, while an ExternalSegment refers to an audience that was not generated in Platform. |
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 a Platform-generated audience or an externally generated audience.
code language-json |
---|
|
Delete an audience delete
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}
{AUDIENCE_ID}
id
field, and is not the audienceId
field.Request
code language-shell |
---|
|
Response
A successful response returns HTTP status 204 with no message.
Retrieve multiple audiences bulk-get
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
code language-shell |
---|
|
Response
A successful response returns HTTP status 207 with information with your requested audiences.
code language-json |
---|
|
Next steps
After reading this guide, you now have a better understanding of how to create, manage, and delete audiences using the Adobe Experience Platform API. For more information about audience management using the UI, please read the segmentation UI guide.