Activate audiences on-demand via the ad-hoc activation API

Overview overview

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

Use the ad-hoc activation API to activate audiences on-demand to batch file-based destinations and, starting with v4, to streaming and API-based destinations. See Trigger an ad-hoc activation run further below in this tutorial.

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.

Use cases use-cases

Flash sales or promotions flash-sales

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 current-events

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 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.

Audience refresh for streaming destinations audience-refresh-streaming

A streaming or API-based destination applies a time-to-live (TTL) to the audience membership it receives from Adobe Experience Platform. When that TTL expires on the destination side, previously qualified profiles are treated as inactive, even though they remain qualified in Experience Platform. The marketing team can use v4 of the ad-hoc activation API to resend an audience’s full current membership on-demand, without waiting for the next scheduled refresh. See Trigger an ad-hoc activation run further below in this tutorial.

Guardrails guardrails

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

Segmentation considerations 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 prerequisites

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

Step 2: Gather credentials credentials

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:

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.

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

API reference documentation api-reference-documentation

You can find accompanying reference documentation for all the API operations in this tutorial. See the Ad Hoc Activation API reference.

Step 3: Create activation flow in the Experience Platform UI activation-flow

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) segment-export-id

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.

Step 5: Run the ad-hoc activation job 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.

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.

Request request

For non–segmentation service audiences (for example, external or custom upload audiences), you must specify the audience ID generated by Experience Platform in your request, not the external audience ID. You can find the system-generated ID at the top of the audience summary panel, displayed as ID# followed by a UUID, when you open the audience details page in the audiences UI.

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.
{width="100" modal="regular"}
{width="100" modal="regular"}

Request with export IDs request-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"
   ]
}

Response 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"
      }
   ]
}

API error handling api-error-handling

Destination SDK API endpoints follow the general Experience Platform API error message principles. See 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 specific-error-messages

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.

(Beta) Trigger an ad-hoc activation run streaming-destinations

Use v4 of the ad-hoc activation API to trigger Activate now, an on-demand, full-membership refresh of an audience to a streaming or API-based destination.

Many streaming and API-based destinations apply a time-to-live (TTL) to the audience membership they receive from Adobe Experience Platform. When that TTL expires on the destination side, previously qualified profiles are treated as inactive, even though they remain qualified in Experience Platform. Trigger a v4 ad-hoc activation run to resend every currently qualified profile through the existing streaming activation pipeline, without waiting for the next scheduled refresh.

You can also trigger this refresh from the Experience Platform UI. Read Activate now for streaming destinations.

Streaming guardrails streaming-guardrails

Ad-hoc activation to streaming destinations enforces the following limit:

Streaming request streaming-request

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}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -H 'Accept: application/vnd.adobe.adhoc.streaming.activation+json; version=1' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ]
   }
}'

Streaming response streaming-response

A successful response returns HTTP status 202 (Accepted) and creates one streaming job per requested audience.

{
   "jobs":[
      {
         "jobId":"88d6da63-dc97-460e-b781-fc795a7386d9",
         "flowId":"ef2dcbd6-36fc-49a3-afed-d7b8e8f724eb",
         "audienceId":"db8961e9-d52f-45bc-b3fb-76d0382a6851",
         "imsOrgId":"{ORG_ID}",
         "status":"QUEUED",
         "createdAt":"2026-08-17T14:00:00Z"
      }
   ]
}

If the same audience was already triggered for this dataflow within the last 24 hours, the request is rejected with HTTP 409 and a Retry-After header indicating how many seconds until you can try again.

Related information related-information