Create and activate an external audience using the API

This tutorial walks through the steps required to create an external audience using the Adobe Experience Platform APIs.

Getting started

This tutorial requires a working understanding of the various Experience Platform services involved in creating an external audience. Before beginning this tutorial, please read the documentation for the following services:

Required headers

This tutorial also requires you to have completed the authentication tutorial in order to successfully make calls to Experience Platform APIs. Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:

All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Experience Platform APIs require a header that specifies the name of the sandbox the operation will take place in:

All POST, PUT, and PATCH requests require an additional header:

Prepare the external audience prepare

Before you can create an external audience within Experience Platform, you’ll need to prepare a file that contains the audience data.

For this example, you should use a CSV file. Ensure your CSV file contains at least one column with an identity value such as an ECID, email ID, or CRM ID. Additionally, make sure contains all the enrichment attributes you’ll need for segmentation and activation.

You’ll also need to make sure that the file conforms to your Experience Platform schema’s requirements. For more information on creating a schema, read either the tutorial on creating a schema using the API or the tutorial on creating a schema using the UI.

After you’ve confirmed your CSV file contains all the information you need and conforms to the schema, you’ll need to upload the CSV file to your cloud storage provider so you can use sources to ingest the data into Experience Platform. For more information on using a cloud storage source, read either the tutorial on exploring cloud storage options using the API or the sources overview.

Create an external audience create

After preparing your CSV file, you can now start the process of creating the external audience.

You can create an external audience by making a POST request to the /external-audience/ endpoint.

When making this request, you’ll need to specify the following information:

For more detailed information on how to use this endpoint, read the external audiences endpoint guide.

curl -X POST https://platform.adobe.io/data/core/ais/external-audience/ \
 -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 '{
        "name": "Sample external audience",
        "description": "A sample version of an external audience",
        "fields": [
            {
                "name": "ppid",
                "type": "string",
                "identityNs": "email"
            },
            {
                "name": "list_id",
                "type": "string",
                "labels": ["core/C2", "custom/deep"]
            },
            {
                "name": "delete",
                "type": "number"
            },
            {
                "name": "process_consent",
                "type": "string"
            }
        ],
        "sourceSpec": {
            "params": {
                "path": "activation/sample-source/example.csv",
                "type": "file",
                "sourceType": "Cloud Storage",
                "baseConnectionId": "1d1d4bc5-b527-46a3-9863-530246a61b2b"
            }
        },
        "ttlInDays": "40",
        "labels": ["core/C1"],
        "audienceType": "people",
        "originName": "CUSTOM_UPLOAD"
    }'

After making this request, make sure to note the operationId you receive from the response so you can retrieve the audience ID.

Retrieve audience ID retrieve-audience-id

Now that you’ve created the external audience, you’ll need to get the audience ID so you can ingest the audience into Experience Platform.

You can retrieve the audience ID by making a GET request to the /external-audiences/operations endpoint and providing the ID of the operation you previously received from the create external audience response.

For more detailed information on how to use this endpoint, read the external audience endpoint guide.

curl -X GET https://platform.adobe.io/data/core/ais/external-audience/operations/{OPERATION_ID} \
 -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}'

After making this request, make sure you note the audienceId you receive from the response so you can trigger the ingestion job for the audience.

Start audience ingestion start-ingestion

Since you’ve got your audienceId, you can now trigger the ingestion of your external audience into Experience Platform.

You can start an audience ingestion by making a POST request to the following endpoint while providing the audience ID. Additionally, you’ll need to specify the starting time to determine which files will be processed.

For more detailed information on how to use this endpoint, read the external audiences endpoint guide

curl -X POST https://platform.adobe.io/data/core/ais/external-audience/{AUDIENCE_ID}/runs \
 -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 '{
    "dataFilterStartTime": 764245635
 }'

After making this request, make sure to note the runId you receive from the response so you can monitor the ingestion status.

Monitor ingestion status monitor-ingestion

After you’ve triggered the audience ingestion, you can now monitor the ingestion’s progress to confirm the ingestion’s success and validate the audience’s availability for downstream activation.

You can retrieve the status of an audience ingestion by making a GET request to the following endpoint while providing both the audience and run IDs.

For more detailed information on how to use this endpoint, read the external audience endpoint guide.

curl -X GET https://platform.adobe.io/data/core/ais/external-audience/{AUDIENCE_ID}/runs/{RUN_ID} \
 -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}'

Next steps next-steps

Once you’ve confirmed that the external audience has been successfully ingested, you can see it in Audience Portal and use it in downstream services such as destinations.

For more information about Audience Portal, read the Audience Portal UI guide. For more information on destinations, read the destinations overview.