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

Overview 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 Platform every 24 hours.

Use cases 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 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

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:

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.

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

Step 3: Create activation flow in the 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 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

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

Request with export IDs (to be deprecated) request-deprecated

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. Refer to API status codes and request header errors in the 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.

Related information related-information