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.
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 Platform every 24 hours.
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.
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.
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.
Keep in mind the following guardrails when using the ad-hoc activation API.
Adobe Experience Platform runs scheduled segmentation jobs once every 24 hours. The ad-hoc activation API runs based on the latest segmentation results.
Before you can make calls to the Adobe Experience Platform APIs, make sure you meet the following prerequisites:
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.In order to make calls to 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:
{ACCESS_TOKEN}
{API_KEY}
{ORG_ID}
Resources in Experience Platform can be isolated to specific virtual sandboxes. In requests to Platform APIs, you can specify the name and ID of the sandbox that the operation will take place in. These are optional parameters.
{SANDBOX_NAME}
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:
application/json
Before you can activate audiences through the ad-hoc activation API, you must first have an activation flow configured in the 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:
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.
Adobe Experience Platform runs scheduled segmentation jobs once every 24 hours. The ad-hoc activation API runs based on the latest segmentation results.
Note the following one-time constraint: Before running an ad-hoc activation job, make sure that at least 20 minutes have passed from the moment that the audience was first activated according to the schedule you set in Step 3 - Create activation flow in the 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.
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.
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 |
---|---|
|
The IDs of the destination instances to which you want to activate audiences. You can get these IDs from the 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. |
|
The IDs of the audiences that you want to activate to the selected destination. You can use the ad-hoc API to export 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. ![]() ![]() |
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 |
---|---|
|
The IDs of the destination instances to which you want to activate audiences. You can get these IDs from the 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. |
|
The IDs of the audiences that you want to activate to the selected destination. |
|
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. |
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. |
Destination SDK API endpoints follow the general Experience Platform API error message principles. Refer to API status codes and request header errors in the Platform troubleshooting guide.
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. |