Retrieving Segment Metadata retrieving-segment-metadata

When Audience Manager sends segment information to a data partner, it identifies these objects with numeric IDs. As a data partner, when you share this information with your customers (or work with it yourself), an actual name and description provide a better experience for customers in reports, dashboards, or other user interfaces (UI). Data partners can make these friendly names available to their customers with either the manual or automated methods described in this section.

Manual method manual-method

As a data partner, you’re probably used to getting audience metadata from your customers through manual processes. This could include files attached to emails or from customers adding that data through a UI you’ve built and maintained for this purpose. These processes work, but they’re often cumbersome, time consuming, and may require manual data entry work. These methods are often used to help get an integration up and running quickly, but they do not provide the best customer experience in the long run. As an alternative, you can use the Audience Manager API to get segment metadata automatically.

Automated method automated-method

Audience Manager provides a set of REST APIs that let you retrieve segment metadata automatically. With the API, you can create jobs that retrieve segment metadata at scheduled intervals or automatically, whenever you process Audience Manager data and find a new segment ID. See the steps below for more information.

Step 1: Review the Audience Manager APIs

The Getting Started with REST APIs section contains information about general requirements, authentication, available methods, etc. This is a good place to begin if you haven’t worked with the Audience Manager API before.

Step 2: Request OAuth2 access credentials

You need a client ID and secret to make API calls. You can obtain a client ID and secret from your integration specialist during the integration set up process. You can also send an email request to Audience Manager Customer Care at

Step 3: Collect customer-specific information from each integrated customer

Request the following from each integrated customer:

  • Username: This is for a restricted user that has read-only permissions for the destination associated with a specific integration.
  • Password: The user password.
  • Destination ID: This is the ID (an integer) associated with the destination created for the specific server-to-server integration.

Step 4: Retrieve segment metadata with an API call

After completing the previous steps, you can use a GET method to retrieve segment metadata. For a sample request and response, see Return Destination Mappings. This call returns segment data formatted as key-value pairs in a JSON object. Some of the important segment attributes returned in the response are listed in the following table.

The Audience Manager segment ID.
The segment name.
Some text that briefly describes the segment.

The current status of the segment mapping. Returned status options include:

  • active
  • inactive
  • deleted