Adobe Audience Manager: Creating Onboarded Traits with API

Last updated: Aug 08, 2024

Adobe Audience Manager: Creating Onboarded Traits with API

Some integrations with Adobe Audience Manager (AAM) require pushing audiences into the AAM platform. Each of these audiences is represented as an AAM Trait - more specifically an "Onboarded" Trait (yes, there are different types of Traits). The Trait must be created within the AAM account before all of the user data for the audience can be transferred.

This article will show you one method of creating an Onboarded Trait using the AAM REST API. Other methods will be covered in separate articles, including using the AAM user interface and the Bulk Management Tool (link).

Prerequisites

User Permissions - you must be able to sign in to the AAM user interface with a user that has adequate permissions to create Data Sources and Traits.
OAuth Credentials - you must have a Client ID and Secret. This is obtained in your communication with the partner integrations team (mcpi).
Data Source - all Traits must be linked to a Data Source, so create one to hold your Trait(s) if you haven't already.

Step 1 - Retrieve an access_token

Use either Adobe Developer console OAuth Authentication to retrieve an "access_token".

This token is required to be passed in the "Authorization" header for each API call going forward.

Example header --

Authorization: Bearer [token goes here]

Step 2 - Create the Trait folder

All Traits must live inside of a Trait folder. Trait folders exist to keep Traits organized within a taxonomy.

Note: Screenshots that follow are from the API Swagger docs where you can make the actual API calls from within the documentation. See Trait Folders.

To get a list of all the Trait folders for your account you can make the following GET call.

GET https://api.demdex.com/v1/folders/traits/

Highlighted in the response above is the parent folder named "A Plus", in which we will be creating a new folder. We've made this call so that we can get the folderId of the parent and its pid (requirements when creating any new folder).

To create a new folder named "Income range" within the "A Plus" folder we would make this call.

POST https://api.demdex.com/v1/folders/traits/

{
  "parentFolderId": 768590,
  "name": "Income range",
  "pid": 7146
}

The API response would look similar to this.

Note, if you are a Marketplace partner, a Trait folder will automatically be created for you under the "3rd-Party Data" folder each time you create a new Data Source. The Trait folder will be named the same as your Data Source name. Use the steps above to add new sub folders as needed within those auto created folders.

It is also important to keep the following in mind with Trait folders -

There is a limit on the total number of Trait folders that can exist for your account. That limit is 2,000 at the time this article was created. Look under Admin > Limits within the UI to see how you are tracking for this limit.
Once you create a folder under the folder structure for one Data Source, do NOT move that folder to exist within the folder structure of a different Data Source. Doing so will result in visibility and access issues for customers that later subscribe to your data offering.
You can create up to 3 levels of sub-folders beneath your data source folder. Trying to create additional levels will result in an error.

Step 3 - Create the Trait

Now that a folder exists, let's create a Trait within that folder.

Note: Screenshots that follow are from the API Swagger docs where you can make the actual API calls from within the documentation. See Traits API

First we'll show the call. Then we'll briefly go over all of the attributes used in the POST body.

POST https://api.demdex.com/v1/traits
{
  "name": "A Plus > Income range > HH income above $200K",
  "description": "A Plus > Income range > HH income above $200K",
  "comments": "",
  "pid": 7146,
  "ttl": 30,
  "folderId": 769662,
  "traitRule": "ic == 12345",
  "dataSourceId": 355894,
  "integrationCode": "",
  "traitType": "ON_BOARDED_TRAIT"
}

Here is some context for the attributes supplied when creating a new Trait.

name - This should describe the audience and include the data provider's brand in most cases.
description - Provides some additional information about the audience if needed.
comments - not required and not used often
pid - this is the ID of the AAM account
ttl - this is the "Expire after" setting in the UI. Upon recognizing a user into this audience, this is the number of days the user will belong to the audience before AAM will expire the user qualification. Should be set to a value between 1 and 30.
folderId - the numeric ID of the Trait folder the Trait should belong to.
traitRule - this is the "Trait Expression" in the UI. This expression is how AAM will recognize which users will qualify for this Trait (belong to this audience) when the data files are processed. In most cases an "ic ==" rule should be used as shown above. In this example, "12345" will be used within the Inbound data files to link users to this Trait.
dataSourceId - this is the numeric ID of the Data Source to which this Trait belongs. The Data Source and the top level Trait folder (child of the "3rd-Party Data" folder) should correspond.
integrationCode - not required.
traitType - for Onboarded Traits this should always have the value "ON_BOARDED_TRAIT"

You can validate the creation of this new Trait folder and Trait by navigating to the Traits area within the AAM user interface.

You have created an Onboarded Trait. Now set up a script to make some more!

Back to articles

Adobe Audience Manager: Creating Onboarded Traits with API