Documentation Experience Platform Destinations Guide

Activate audiences on-demand to batch destinations via the ad-hoc activation API

Last update: April 2, 2025

Topics:
Destinations

CREATED FOR:

Admin
User

IMPORTANT

After completing the Beta phase, the ad-hoc activation API is now generally available (GA) to all Experience Platform customers. In the GA version, the API has been upgraded to version 2. Step 4 (Obtain the latest audience export job ID) is not required anymore, since the API does not require the export ID anymore.

See Run the ad-hoc activation job further below in this tutorial for more information.

Overview

The ad-hoc activation API allows marketers to programmatically activate audience audiences to destinations, in a fast and efficient manner, for situations where immediate activation is required.

Use the ad-hoc activation API to export full files to your desired file reception system. Ad-hoc audience activation is only supported by batch file-based destinations.

The diagram below illustrates the end-to-end workflow for activating audiences via the ad-hoc activation API, including the segmentation jobs that take place in Experience Platform every 24 hours.

ad-hoc-activation

Use cases

Flash sales or promotions

An online retailer is preparing a limited flash sale and wants to notify customers on a short notice. Through the Experience Platform ad-hoc activation API, the marketing team can export audiences on-demand, and quickly send promotional emails to the customer base.

Current events or breaking news

A hotel expects inclement weather over the following days, and the team wants to inform the arriving guests quickly, so they can plan accordingly. The marketing team can use the Experience Platform ad-hoc activation API to export audiences on-demand, and notify the guests.

Integration testing

IT managers can use the Experience Platform ad-hoc activation API to export audiences on-demand, so they can test their custom integration with Adobe Experience Platform, and ensure everything is working correctly.

Guardrails

Keep in mind the following guardrails when using the ad-hoc activation API.

Currently, each ad-hoc activation job can activate up to 80 audiences. Attempting to activate more than 80 audiences per job will cause the job to fail. This behavior is subject to change in future releases.
Ad-hoc activation jobs cannot run in parallel with scheduled audiences export jobs. Before running an ad-hoc activation job, make sure the scheduled audience export job has finished. See destination dataflow monitoring for information on how to monitor the status of activation flows. For example, if your activation dataflow shows a Processing status, wait for it to finish before running the ad-hoc activation job.
Do not run more than one concurrrent ad-hoc activation job per audience.

Segmentation considerations

Adobe Experience Platform runs scheduled segmentation jobs once every 24 hours. The ad-hoc activation API runs based on the latest segmentation results.

Step 1: Prerequisites

Before you can make calls to the Adobe Experience Platform APIs, make sure you meet the following prerequisites:

You have an organization account with access to Adobe Experience Platform.
Your Experience Platform account has the developer and user roles enabled for the Adobe Experience Platform API product profile. Contact your Admin Console administrator to enable these roles for your account.
You have an Adobe ID. If you do not have an Adobe ID, go to the Adobe Developer Console and create a new account.

Step 2: Gather credentials

In order to make calls to Experience Platform APIs, you must first complete the authentication tutorial. Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:

Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {API_KEY}
x-gw-ims-org-id: {ORG_ID}

Resources in Experience Platform can be isolated to specific virtual sandboxes. In requests to Experience Platform APIs, you can specify the name and ID of the sandbox that the operation will take place in. These are optional parameters.

x-sandbox-name: {SANDBOX_NAME}

NOTE

For more information on sandboxes in Experience Platform, see the sandbox overview documentation.

All requests that contain a payload (POST, PUT, PATCH) require an additional media type header:

Content-Type: application/json

Step 3: Create activation flow in the Experience Platform UI

Before you can activate audiences through the ad-hoc activation API, you must first have an activation flow configured in the Experience Platform UI, for the chosen destination.

This includes going into the activation workflow, selecting your audiences, configuring a schedule, and activating them. You can use the UI or API to create an activation flow:

Step 4: Obtain the latest audience export job ID (Not required in v2)

IMPORTANT

In the v2 of the ad-hoc activation API, you do not need to obtain the latest audience export job ID. You can skip this step and proceed to the next one.

After you configure an activation flow for your batch destination, scheduled segmentation jobs start running automatically every 24 hours.

Before you can run the ad-hoc activation job, you must obtain the ID of the latest audience export job. You must pass this ID in the ad-hoc activation job request.

Follow the instructions described here to retrieve a list of all the audience export jobs.

In the response, look for the first record that includes the schema property below.

"schema":{
   "name":"_xdm.context.profile"
}

The audience export job ID is in the id property, as shown below.

audience export job ID

Step 5: Run the ad-hoc activation job

Adobe Experience Platform runs scheduled segmentation jobs once every 24 hours. The ad-hoc activation API runs based on the latest segmentation results.

IMPORTANT

Note the following one-time constraint: Before running an ad-hoc activation job, make sure that at least one hour has passed from the moment that the audience was first activated according to the schedule you set in Step 3 - Create activation flow in the Experience Platform UI.

Before running an ad-hoc activation job, make sure the scheduled audience export job for your audiences has finished. See destination dataflow monitoring for information on how to monitor the status of activation flows. For example, if your activation dataflow shows a Processing status, wait for it to finish before running the ad-hoc activation job to export a full file.

Once the audience export job has completed, you can trigger the activation.

NOTE

Currently, each ad-hoc activation job can activate up to 80 audiences. Attempting to activate more than 80 audiences per job will cause the job to fail. This behavior is subject to change in future releases.

Request

IMPORTANT

It is mandatory to include the Accept: application/vnd.adobe.adhoc.activation+json; version=2 header in your request in order to use v2 of the ad-hoc activation API.


curl --location --request POST 'https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun' \
--header 'x-gw-ims-org-id: 5555467B5D8013E50A494220@AdobeOrg' \
--header 'Authorization: Bearer {{token}}' \
--header 'x-sandbox-id: 6ef74723-3ee7-46a4-b747-233ee7a6a41a' \
--header 'x-sandbox-name: {sandbox-id}' \
--header 'Accept: application/vnd.adobe.adhoc.activation+json; version=2' \
--header 'Content-Type: application/json' \
--data-raw '{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   }
}'

Property

Description

destinationId1
destinationId2

The IDs of the destination instances to which you want to activate audiences. You can get these IDs from the Experience Platform UI, by navigating to Destinations > Browse tab, and clicking on the desired destination row to bring up the destination ID in the right rail. For more information, read the destinations workspace documentation.

segmentId1
segmentId2
segmentId3

The IDs of the audiences that you want to activate to the selected destination. You can use the ad-hoc API to export Experience Platform-generated audiences as well as external (custom upload) audiences. When activating external audiences, use the system-generated ID instead of the audience ID. You can find the system-generated ID in the audience summary view in the audiences UI.

View of the audience ID that should not be selected.

View of the system-generated audience ID that should be used.

Request with export IDs


curl -X POST https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   },
   "exportIds":[
      "exportId1"
   ]
}

Property

Description

destinationId1
destinationId2

The IDs of the destination instances to which you want to activate audiences. You can get these IDs from the Experience Platform UI, by navigating to Destinations > Browse tab, and clicking on the desired destination row to bring up the destination ID in the right rail. For more information, read the destinations workspace documentation.

segmentId1
segmentId2
segmentId3

The IDs of the audiences that you want to activate to the selected destination.

exportId1

The ID returned in the response of the audience export job. See Step 4: Obtain the latest audience export job ID for instructions on how to find this ID.

Response

A successful response returns HTTP status 200.

{
   "order":[
      {
         "segment":"db8961e9-d52f-45bc-b3fb-76d0382a6851",
         "order":"ef2dcbd6-36fc-49a3-afed-d7b8e8f724eb",
         "statusURL":"https://platform.adobe.io/data/foundation/flowservice/runs/88d6da63-dc97-460e-b781-fc795a7386d9"
      }
   ]
}

Property

Description

segment

The ID of the activated audience.

order

The ID of the destination to which the audience was activated.

statusURL

The status URL of the activation flow. You can track the flow progress using the Flow Service API.

API error handling

Destination SDK API endpoints follow the general Experience Platform API error message principles. Refer to API status codes and request header errors in the Experience Platform troubleshooting guide.

API error codes and messages specific to the ad-hoc activation API

When using the ad-hoc activation API, you can come across error messages that are specific to this API endpoint. Review the table to understand how to address them when they do appear.

Error message

Resolution

Run already going on for audience segment ID for order dataflow ID with run id flow run ID

This error message indicates that an ad-hoc activation flow is currently ongoing for an audience. Wait for the job to finish before triggering the activation job again.

Segments <segment name> are not part of this dataflow or out of schedule range!

This error message indicates that the audiences you selected to activate are not mapped to the dataflow or that the activation schedule set up for the audiences has either expired or not yet started. Check if the audience is indeed mapped to the dataflow and verify that the audience activation schedule overlaps with the present date.

recommendation-more-help

Activate audiences on-demand to batch destinations via the ad-hoc activation API

Overview

Use cases

Flash sales or promotions

Current events or breaking news

Integration testing

Guardrails

Segmentation considerations

Step 1: Prerequisites

Step 2: Gather credentials

Step 3: Create activation flow in the Experience Platform UI

Step 4: Obtain the latest audience export job ID (Not required in v2)

Step 5: Run the ad-hoc activation job

Request

Request with export IDs

Response

API error handling

API error codes and messages specific to the ad-hoc activation API

Related information