Building audiences

An audience is a specific person or group of people that you want to reach with a campaign. Audiences are made up of included and excluded data groups. Data groups are made up of data elements (first-party data segments or third-party data segments). When you add multiple elements to a data group, you grow the audience. When you add multiple data groups to an audience, you shrink the audience.

Data elements

Data elements are segments of information like cookies and various IDs (such as device IDs and Unified IDs like UID2 and EUID).

Data elements can be combined into data groups.

Data groups

A data group is a collection of first-party and/or third-party data elements that are combined using an OR (union) operator. For example, a data group with data element 1 and data element 2 would look for users that match both data element 1 or data element 2.

When creating an audience, you can use data groups to include or exclude their data elements for targeting. Included data groups target only the specified segments of users, while excluded data groups target everyone except the specified segments of users. You can use both included and excluded groups to create the audience you want to target.

Here's what you need to know about data groups when building your audience:

• If more than one data group is included in an audience, a user must match all of the included data groups to be targeted.
• If more than one data group is excluded in an audience, a user may match any of the excluded data groups to be removed from targeting.
• If a user matches both included and excluded data groups, the user will be excluded from the audience.
• Excluding third-party data elements from a data group has a $0.09 CPM fee, in addition to any fee charged by the data provider to use the segment.

The following diagram illustrates the audience segment that is targeted when multiple data groups are included and excluded within an audience.

Audience creation workflow

To create an audience, complete the following steps:

1. Send first-party data or use third-party data buyable within the platform.
2. Look up first-party data and third-party data element IDs to use within a data group.
3. Create data groups to include in or exclude from audiences.
4. Assign data groups to audiences.
5. Assign audiences to ad groups.

The following sections provide examples for these and other related tasks.

Data element tasks

The following table lists the tasks for managing data elements in both the Platform and Data API.

NOTE: The Data API requires a different authentication.

First-party data elements: Look-up task examples

You can look up first-party data elements by using a variety of filters and sorting, which can be combined to find relevant segments more efficiently.

NOTE: The lookup endpoints return the number of active IDs from the last 7 days and received IDs from the last 30 days. For details, see Unique ID counting methodologies.

The following sections provide examples of different ways of looking up first-party data elements:

• By advertiser
• By unique count
• By search terms
• By data types
• By lookalike model result status

Look up all first-party data elements for an advertiser

The following is a POST /v3/dmp/firstparty/advertiser request body example with the AdvertiserId property.

{
	"AdvertiserId": "advabc",
	"PageStartIndex": 0,
	"PageSize": 10
}

Look up first-party data elements by unique count

The following is a POST /v3/dmp/firstparty/advertiser request body example with the AdvertiserId and UniqueCountMinimum properties.

{
	"AdvertiserId": "advabc",
	"UniqueCountMinimum": 5000,
	"PageStartIndex": 0,
	"PageSize": 10
}

Look up first-party data elements by search terms

Search terms may be added to the request to filter results where the search term matches the data element's FirstPartyDataId, Name, or DataType.

The following is a POST /v3/dmp/firstparty/advertiser request body example with search terms.

{
	"AdvertiserId": "advabc",
	"SearchTerms": ["auto"],
	"PageStartIndex": 0,
	"PageSize": 10
}

Look up first-party data elements by data types

The following is a POST /v3/dmp/firstparty/advertiser request body example with data types.

{
	"AdvertiserId": "advabc",
	"DataTypes": ["ImportedAdvertiserData","Keyword"],
	"PageStartIndex": 0,
	"PageSize": 10
}

Look up first-party data elements by lookalike model result status

The following is a POST /v3/dmp/firstparty/advertiser request body example with a LookAlikeModelResultStatuses property.

{
	"AdvertiserId": "advabc",
	"LookAlikeModelResultStatuses": "Ready",
	"PageStartIndex": 0,
	"PageSize": 10
}

Remove inactive users from first-party data segments

To remove inactive users from your data segment, in a POST /data/advertiser call, set the TTLInMinutes property to 0 for that user.

TIP: To delete the whole segment, set the TTLInMinutes property to 0 for all IDs in the segment.

{
   "AdvertiserId":"yourAdvertiserId",
   "Items":[
      {
         "TDID":"123e4567-e89b-12d3-a456-426652340000",
         "Data":[
            {
               "Name":"1210",
               "TimestampUtc": "2023-11-11T10:11:30+5000",
               "TTLInMinutes":0
            },
            {
               "Name":"1160",
               "TimestampUtc": "2023-11-13T09:35:30+5000",
               "TTLInMinutes":0
            }
         ]
      }
   ]
}

Third-party data elements: Look-up task examples

You can look up third-party data elements by using a variety of filters and sorting, which can be combined to find relevant segments more efficiently.

NOTE: The lookup endpoints return the number of active IDs from the last 7 days and received IDs from the last 30 days. For details, see Unique ID counting methodologies.

The following sections provide examples of different ways of looking up third-party data elements:

• By advertiser
• By unique count
• By search terms
• By demographic category
• By data rate
• By ad environment

Look up all third-party data elements for an advertiser

The following is a POST /v3/dmp/thirdparty/advertiser request body example with the AdvertiserId property.

{
	"AdvertiserId": "advabc",
	"PageStartIndex": 0,
	"PageSize": 10
}

Look up third-party data elements by unique count

The following is a POST /v3/dmp/thirdparty/advertiser request body example with the AdvertiserId and UniqueCountMinimum properties.

{
	"AdvertiserId": "advabc",
	"UniqueCountMinimum": 5000,
	"PageStartIndex": 0,
	"PageSize": 10
}

Look up third-party data elements by search terms

The following is a POST /v3/dmp/thirdparty/advertiser request body example with search terms.

IMPORTANT: All terms must be matched in the Name or FullPath in order for a result to be returned.

{
	"AdvertiserId": "advabc",
	"SearchTerms": ["auto"],
	"PageStartIndex": 0,
	"PageSize": 10
}

Look up third-party data elements by demographic category

To look up category IDs, use GET /v3/dmp/thirdparty/facets/{advertiserId}.

The following is a POST /v3/dmp/thirdparty/advertiser request body example with the CategoryId of 526 for the demographic category including ages 18-24 years.

{
	"AdvertiserId": "advabc",
	"CategoryIds": [526],
	"PageStartIndex": 0,
	"PageSize": 10
}

Look up third-party data elements by data rate

You can filter segments that have a certain data rate or data rate type.

The following is a POST /v3/dmp/thirdparty/advertiser request body example with the CPMFilter filter.

{
	"AdvertiserId": "advabc",
	"DataRateFilters": {
    	"CPMFilter": {
      		"MinimumCPM": {
        		"Amount": 3,
        		"CurrencyCode": "USD"
      		},
      		"MaximumCPM": {
        		"Amount": 7,
        		"CurrencyCode": "USD"
     		}
    	}
  	},
	"PageStartIndex": 0,
	"PageSize": 10
}

Look up third-party data elements by ad environment

You can filter segments by either Web or InApp ad environment.

The following is a POST /v3/dmp/thirdparty/advertiser request body example with the InApp filter.

{
	"AdvertiserId": "advabc",
	"AdEnvironment": "InApp",
	"PageStartIndex": 0,
	"PageSize": 10
}

Third-party data elements similar to your first-party data element: Look-up tasks

NOTE: Third-party data elements are only available in our production environment. They are not available in our sandbox environment.

Look up eligible first-party data segments

For the best probability of having enough first-party data to generate a lookalike model, search for eligible first-party segments that have a minimum unique count ranging from 1000 to 5000.

The following is a POST /v3/dmp/firstparty/advertiser request body example.

{
	"AdvertiserId": "advabc",
	"UniqueCountMinimum": 4000,
	"LookAlikeModelEligibilities": ["Eligible"],
	"PageStartIndex": 0,
	"PageSize": 10
}

Build a lookalike model of third-party data elements

To build a lookalike model, make a request to GET /v3/dmp/lookalikemodel/build/{firstPartyDataId}.

Check the lookalike model build status

To check the build status of lookalike model, make a request to GET /v3/dmp/lookalikemodel/{firstPartyDataId}.

The response includes a LookAlikeBuildStatus, which indicates whether the lookalike model build is processing (Queued) or was completed (Built). The response also includes a LookAlikeModelResultStatus.

The following table explains the LookAlikeModelResultStatus values.

Retrieve third-party data elements from the lookalike model

Search for the results of the build using the query endpoint. The Result object shows the third-party data segments similar to the first-party data segment, as well as a relevance ratio and value ratio to help you evaluate the best segments to use in your audience. Use Result.ThirdPartyData.ThirdPartyDataId in your data groups.

The following is a POST /v3/dmp/lookalikethirdpartydata/query request body example.

{
	"FirstPartyDataId": 1234567,
	"PageStartIndex": 0,
	"PageSize": 10
}

Data group tasks

Create data groups

NOTE: Data groups are created using the Platform API endpoints. For details, see Foundations.

Here's what you need to know about data groups:

• You share data groups among multiple audiences. Just set the IsSharable property to true.
• To create the data group without third-party data segments that you are not authorized to use, set the SkipUnauthorizedThirdPartyData property to true when specifying third-party IDs. If not specified or set to false, attempting to create a data group with ThirdPartyDataIds you are unauthorized to use will result in an error.
• All third-party data IDs in segments will be validated for biddability. Data group workflows will fail if the ThirdPartyDataIds array contains non-biddable IDs.

TIP: To check if segments are buyable beforehand, use the POST /v3/dmp/thirdparty/advertiser endpoint. Include only third-party data IDs listed in the response.

The following is a POST /v3/datagroup request body example.

{
	"AdvertiserId": "advabc",
	"DataGroupName": "Auto Interest",
	"IsSharable": true,
	"FirstPartyDataIds": [
		1234567
	],
	"ThirdPartyDataIds": [
		"1234567|bluekai"
	],
	"SkipUnauthorizedThirdPartyData": true
}

Audience tasks

Create an audience

The following is POST /v3/audience request body examples.

Target certain data groups and exclude one data group

{
  "AdvertiserId": "adv123",
  "AudienceName": "24-35 Cats Minus Low Value",
  "Description": "Users in the age range 24-35 who are interested in cats and are not low-value users.",
  "IncludedDataGroupIds": [
    "aud1234",
    "aud2345"
  ],
  "ExcludedDataGroupIds": [
    "aud3456"
  ]
}

Target everyone except one data group

{
  "AdvertiserId": "adv123",
  "AudienceName": "Everyone Except Low-Value Users",
  "Description": "Exclude low value users",
  "IncludedDataGroupIds": [],
  "ExcludedDataGroupIds": [
    "aud3456"
  ]
}

Assign an audience to an ad group

The following is a PUT /v3/adgroup request example that shows how to assign an audience to an existing ad group.

{
	"AdGroupId": "adgr123",
	"RTBAttributes": {
		"AudienceTargeting": {
			"AudienceId": "aud1234"
		}
	}
}

• To target everyone (run-of-exchange), do not enable any properties in the RTBAttributes.AudienceTargeting object of the ad group.
• To target only trackable users, on the ad group, enable RTBAttributes.AudienceTargeting.TargetTrackableUsersEnabled to restrict targeting only to users that we can track (users we have a TDID or a device ID for).
  We'll create a new audience for you that includes only trackable users.

NOTE: There is a fee to use this feature which you can be look up by using the ad group's RTBAttributes.AudienceTargeting.TargetTrackableUsersFee object.

To view a full list of Koa features, see Ad groups.

FAQs

We've got answers to your most commonly asked questions.

How is audience different from seed?

Audience and seed are not the same. They are two discrete entities.

A seed is a specific, concentrated group of individuals who represent the core group of people that you want to target. This group typically consists of individuals who have taken valuable actions or exhibit traits that align with your campaign goals. An audience, on the other hand, is an expanded version of the core group, which includes not only the individuals in your seed but also extends to others who share similar traits or behaviors.

Can I create an audience with geolocation data?

Yes. To do this, include your third-party or first-party geofence segment ID in a data group and add it to your audience. For details on how to create first-party geofence data segments, see Geofence targeting.