On-demand recalculation of segments (and other segment API calls)

This article reviews how to use Postman (or other API call utility) to perform an on-demand recalculation of a segment or segments. It details how to obtain credentials to make the call via Adobe.io and the call variables required to execute the request.

Be sure to refer to your specific product licensing when creating segment jobs and schedules: https://helpx.adobe.com/ca/legal/product-descriptions/real-time-customer-data-platform-b2c-edition-prime-and-ultimate-packages.html#:~:text=Real%2DTime%20CDP%20Connections%20means,Adobe%20and%20partner%2Dbuilt%20Extensions

Before starting the exercise, download Postman for your appropriate operating system from https://www.postman.com/downloads/.

Required headers

In order to successfully make calls to Platform APIs. You will need the values for the required headers. Note that the official documentation refers to tokens with single curly brackets {} but Postman requires double curly brackets {{}} around variables. We will first go into how to obtain these values. This is simply a list of what’s required.

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

You will also need the name of the sandbox you’ll be running the APIs against.

x-sandbox-name: {{SANDBOX_NAME}}

To obtain these details, you’ll need to access the Adobe IO developer console: https://developer.adobe.com/console/home. Have your administrator provide you with developer access for AEP and the desired sandbox if you find you do not have access.

Start by creating a new project. From the console, select Create new project.

Then, select Add API.

From the list of available options, select Experience Platform API and then click Next

To obtain access to the API, select the Generate a key pair option and then click Generate keypair.

The key will be generated and an automatic download will start. Click Next. Keep tabs on where the file is downloaded, you will need the file to create the credentials to make the connection.

Select the proper sandbox for your API call (referred to on this display as the product profiles). Ideally you’ll have separate projects and sandboxes for development, QA, and production. Select Save configured API once selected.

Once created, you’ll receive a notification indicating that your API has been configured successfully.

To be able access the API in Postman, you’ll need to generate an Access Token.

When unzipped (decompressed), the file that was previously downloaded includes a “private.key” file. This file should be opened with a text editor and then the contents of the text copied in its entirely into the Private key field.

Once pasted in, click Generate Token.

The generated access token will need to be copied as it must be used to make the connection in Postman. Click Copy and paste the contents into a text editor to keep the code handy.

Next, click on the Download for Postman icon to download a Postman project for this API.

After clicking on the Service Account (JWT) button, you should find a download of a service.postman_environment.json file. This file provides you with most of the variable values you’ll need to make a secure connection.

Now, open Postman.

In Postman, create a new collection. Select Collections and Create Collection.

Name the collection AEP Calls.

Now, click Import and upload the json file that was downloaded in one of the previous steps. This will allow you to import the environment variables required to make calls to your API. Click Import when prompted.

Clicking on the Environments section should show you a new environment will the new variables. Note that the list excludes the JWT_TOKEN value. In the INITIAL VALUE and CURRENT VALUE fields for JWT_TOKEN, paste in the Generated JWT value from the previous step from the Adobe.io console.

We now have the required fields to make the service call. Before we make the call, let’s make sure we have a very small segment we can test an evaluation on.

Sample Segment

In the below example, we’ve created a new segment that we’d like to evaluate. For the evaluation, you will need the ID that is displayed on the segment detail. Clicking the segment ID will show you the segment summary details that include the ID. It is also visible in the URL. Note that in the example below, the segment has not yet been evaluated.

Setting up Postman

In Postman, click on Collections, then expand the AEP Calls collection, then click Add a request.

First, we need to define the API end point we’re going to call. Select POST as the call type (not a GET) to the Jobs API: https://platform.adobe.io/data/core/ups/segment/jobs.

To connect to the API, we need to provide the proper authorization. Click on the Authorization tab and select Bearer Token as the authentication type. Before attempting to provide a variable value, select the proper environment that contains the new variables you’ve imported and provided token values for.

Enter {{JWT_TOKEN}} for the token value. You should notice that type-ahead will start after you enter the first {{. If it does not, ensure you’ve selected the proper environment.

Next, we need to provide the proper Header values to complete the connection.

In the Headers tab, add the x-api-key, x-gw-ims-org-id, and x-sandbox-name. Enter the associated variable into the value column. If you don’t have a variable representing your sandbox name, you can create one in your environment or enter the value manually.

Lastly, in the body, we provide an array of the segments we wish to reevaluate in JSON format. Select the Body tab, and then raw as the format and JSON from the type options. The ID in the example below is the segment ID referenced above.

[
   {
      "segmentId":"15ccd1d6-013b-4319-b210-5111ab31e18a"
   }
]

Once the call is made successfully, the response will details about the request but also includes link details back to obtain the status of the requested job.