Audiences API

If you are a DMP client, you can implement the audience web service to create and manage audiences. An audience contains the users you want deliver to Oracle Data Cloud partners for targeting, modeling, or optimization. You can also analyze an audience to expand it, identify trends, and analyze the performance of its categories.

For example, you can use the audiences API to create a simple audience that includes one segment (such as users interested in purchasing a smart phone) or you can create a complex audience that includes multiple segments (such as user interested in purchasing smart phones and users interested in purchasing laptops), while excluding other segments (such as, users with a specific range of ages and household incomes). For details about creating audiences, see the audience creation reference.

Note: Users no longer create campaigns in the Oracle Data Cloud platform UI. The campaign workflow is now part of the audience workflow. The platform still uses campaigns to manage audience data delivery however. They are created automatically when a UI user delivers an audience. In the APIs, you create and use campaigns as before.

In this topic  

Explore the API

The embedded I/O doc below enables you to explore the API. The I/O  doc explains the parameters for each method and provides templates for your calls. You cannot make live API calls from the tool, however.

Open the link below in a new tab to see the I/O doc in a three-pane format.

https://audiences2.docs.apiary.io

For help with this API, contact My Oracle Support (MOS).

Service URI

The URI for the audiences API is:

services.bluekai.com/Services/WS/audiences

Audiences API use cases

What kind of Audiences can I get from the audiences API?

  • Created audiences: Audiences you have created using the audience builder in the Oracle Data Cloud platform or the audiences API.
  • Received audiences: Audiences that a DMP client has shared with you. You can create a campaign using the received audience or analyze it.

    Audience sharing is typically used by DMP clients to send their audiences to an agency who will then run the campaign for them.

    Audiences can be shared using the audience grant API or the audience management tool in the Oracle Data Cloud platform.

When do I use the audiences API?

  • Audience creation and inventory retrieval
    • Audiences with first-party categories: If you are a DMP client or an audience recipient, you can use the audiences API to create new audiences or get existing audiences. You can then use the segment reach API to get the number of unique users in the audiences.
    • Audiences with third-party categories: If you are a data buyer, you can use the audiences API to create new audiences and get existing audiences that include third-party categories. You can then use the segment reach API to get the number of unique users in the audience.
  • Audience discovery: If you are a DMP client or data buyer that has created audiences, you can use the audiences API to get the composition and configuration of an audience. This helps you create new audiences with similar categories and settings.
  • Audience analytics: If you are a data app partner who is programmatically running audience analytics, you can call the GET method and use the categories in the returned audience as the input for creating audience discovery reports.
  • Data delivery configuration: You can use the audiences API to create a grouping of categories to be delivered to a partner. If you want to deliver an existing audience, use the audiences API’s GET function to get the audience you want to send.
  • Data mapping: Data mapping takes place at the campaign level. This is because the campaignID parameter is included with user data delivered via server data transfer, which is the preferred data delivery method.

Related API calls

API calls you will typically make before and after you use the audiences API:

Related API calls Use case
Audience grant API Share your audience with other DMP partners.
Campaigns API Create instructions for delivering your target audience to DMP partners.
Pixel URL API Associate a destination with your campaign.
Segment reach API Get the estimated number of unique user in an audience before creating and delivering it.
Categories API View the first- and third-party categories that you can use to create your target audience.
User data API Programmatically deliver the campaigns and categories for which users have qualified.

GET response summary

The audiences API GET request returns an audience or a list of audiences.

Property Type Description
archived boolean Indicates whether an audience has been archived. Data is not delivered for archived audiences.
audienceGrants object

An object containing properties related to audiences you have received from another DMP partner. For each audience shared with you, the following properties are included:

  • sharedDate: The date when the audience was initially shared with you (in YYYY-MM-DD format)
  • withdrawByDate: The date when the shared audience will be withdrawn (in YYYY-MM-DD format)
  • emailNotes: Any user-specified notes associated with the emailing of the audience
audienceID integer The unique identifier assigned to the audience
campaigns object

An object including a list of the campaigns to which the audience has been added. For each campaign, the following properties are included:

  • campaignID: A unique identifier assigned to the campaign. This property is only returned if you own the campaign.
  • partnerID: The unique identifier of the DMP partner that shared this campaign with you. This property is only returned if you do not own the campaign.
  • name: The user-specified name for the campaign.
createDate date The date when the audience was created (in YYYY-MM-DD format).
countryCodes integer

The two-letter ISO 3166-1 alpha-2 country codes of the countries the audience is targeting.
deviceTypeId integer

Indicates on which devices your audience is targeting users. This may be one of the following values:

  • 0: All devices (desktop and mobile)
  • 1: Desktop devices
  • 2: Mobile devices
name string The user-specified name of the audience.
partnerID integer The unique identifier assigned to your Oracle Data Cloud platform seat.
prospecting boolean A legacy field.
recency integer The maximum number of days users must have been tagged with a category attribute to be included in your audience. The default recency is 0, which means 90 days.
retargeting boolean A legacy field.
segment object

An object representing an audience with the following structure:

  • One AND object representing the audience.
  • One or more OR objects in the AND object representing the individual segments in the audience.
  • A list of one or more category IDs (cat) in each OR object representing the categories in the segment.

This object is populated only in GET (read) responses. It is empty for GET (list) responses.
status string

Indicates whether the audience is being shared. This property may be one of the following values:

  • Saved: The audience is active, but is not being shared.
  • Shared: You have shared the audience with another DMP partner.
  • Received: A DMP partner has received the audience you are sharing with them.
  • Withdrawn: The audience is no longer being shared.
totalCount integer The total number of audiences returned by the GET (list) request

Audience creation reference (for POST and PUT requests)

In Oracle Data Cloud APIs, an audience is represented by a series of segments that are combined with AND logic

{ "AND": [<Segment1>, <Segment2>, ...] }

where each segment has one or more categories that are combined using OR logic:

{"OR": [{"cat1", <categoryID>}, {"cat2", <categoryID>), ...] }

If your audience includes multiple segments, the user must meet the criteria in all of the segments to be included in your target audience (an AND condition).

If a segment includes multiple categories, a user only needs to have been tagged with one of the categories to be included in the segment (an OR condition).

Adding a category to a single segment

You can create a simple audience that includes a single segment with one category.

For example, if you add In-Market > Autos (categoryID = 17) to a segment, the user needs to have been tagged with that category to be included in your audience.

The following code snippet demonstrates a JSON-body for an audiences API POST request that includes a single segment with one category:

"segment": {"and": [{"or": [{"cat": 17}]}]}

Adding multiple categories to a segment

You can add multiple categories to a segment, which creates an OR condition. This means that a user only needs to have been tagged with one of the categories in the segment to be included in your target audience.

For example, if you add In-Market > Retail > Video Games > Systems > Sony > Playstation (categoryID = 7628) and In-Market > Retail > Video Games > Systems > Microsoft > XBOX (categoryID = 7624) to a segment, the user only needs to have been tagged with one of the video game systems to be included.

The following code snippet demonstrates a JSON-body for a audiences API POST request that includes multiple categories in a single segment:

segment": {"AND": [{"OR": [{"cat": 7624},{"cat": 7628,"freq": [1, null]}]}]}

Including multiple segments in an audience

Your target audience may also include multiple segments, which creates an AND condition. This means that a user must meet the criteria in all of the segments to be included in your target audience.

For example, if you add In-Market > Travel > Air Travel (categoryID = 139) to one segment and In-Market > Travel > Cruises (categoryID = 6089) to another segment, the user needs to have been tagged with both categories to be included.

The following code snippet a JSON-body for a audiences API POST request that includes multiple segments:

"segment": {"AND": [{"OR": [{"cat": 139}]},{"OR": [{"cat": 6089}]}]}

Excluding segments

Your target audience may exclude one or more categories in a segment, which creates a NOT condition. This means that users in the excluded segment will not be included in your target audience.

For example, if you include users in the In-Market > Travel > Cruises category (categoryID = 6089) but exclude users in the Demographic > Premium Demographic > Income > $0-$14,999 (categoryID = 5814) and Demographic > Premium Demographic > Income > $15,000-$19,999 (categoryID = 71) categories, those users who are in-market for a cruise but are in the specified lower incomes will not be included from your target audience.

The following code demonstrates a JSON-body for an audiences API POST request that includes and excludes different segments:

"segment": {"AND": [{"OR": [{"cat": 18}]},{"NOT": {"OR": [{"cat": 71},{"cat": 5814}]}}]}

Setting the frequency and target device

(Optional) You can specify the frequency and target device in your audiences API POST and PUT requests.

  • Frequency: Frequency represents the number of times users must have qualified for a category since they were initially tagged with it to be included in the query.

    For example, to set the minimum frequency to 10 using the previous example, you would include the freq parameter in the JSON body using the following syntax:

    {"AND": [{"OR": [{"cat": 17,"freq":[10]}]}]}

    To set a range of frequencies (for example 10 to 20), use the following syntax:

    {"AND": [{"OR": [{"cat": 17,"freq":[10,20]}]}]}

  • Device: You can get the reach of your audience based for a specific device type (desktop or mobile) using the device_type parameter. For example to get the reach of your audience on mobile devices only, you would use the following syntax:

    {"AND": [{"OR": [{"cat": 17}]}],"device_type": "mobile"}

    The default device type is All (desktop and mobile). The APIs support the following device types: all (desktop and mobile), desktop, or mobile.

Learn more

Introduction to the Oracle Data Cloud APIs