Audience API

The Audience API placement provides real-time access to user segment and attribute data. It enables third-party systems, such as personalization tools or email marketing platforms, to retrieve detailed segment information about individual users directly through an API.

Concept of the Audience API

The Audience API allows real-time access to data about user segments and attributes (User Categories). The goal is to make this data flexible for use in external systems without requiring direct access to Mapp Marketing Automation.

• User Identification:

  Data is retrieved using:

  • Ever ID: A cookie-based identifier generated by Mapp, useful for anonymous tracking but device-dependent.

  • Customer ID: A stable identifier provided by the customer, such as a hashed email address, enabling consistent tracking across devices and sessions.

  Find more information about user identifiers on this page: User-Centric Tracking (1): An introduction

• Flexibility:

  Customers can define which data is available through the API:

• Segments: Selection of relevant segments.

• User Categories: Attributes such as “Subscriber Status” or “Customer Type.”

• Metrics: Visitor-related metrics such as purchases or engagement.

Use Cases for Audience API Placements

1. Email Personalization

   • Scenario: An email marketing tool uses segment data to dynamically adjust newsletter content.

   • How It Works: The tool calls the API to retrieve the user’s segment list and status (true/false).

   • Example: Offer exclusive deals to premium customers while showing general offers to other segments.
     

2. Onsite Personalization via JavaScript

   • Scenario: A personalization tool retrieves segment data for the current user in real-time to display customized website content.

   • How It Works: The API provides User Categories and their current values, which are used to adapt the user experience dynamically.

   • Example: Display tailored product recommendations or exclusive messages based on user attributes.

Configuration for Audience API

Step 1: Configure the Audience API Placement

To configure an Audience API placement, navigate to Marketing Automation > Placements > Audience API and follow these steps:

1. Add a Title: Provide a unique name for the placement.

2. Select Segments: Choose the relevant segments to include in the API response.

3. Select User Categories & Metrics:

   • User Categories: Choose the attributes to include in the response (called “URM Categories” in the frontend).

   • Metrics: Select the visitor metrics to be included in the response.

4. Save: Finalize your configuration.

Step 2: Retrieve API Details

After configuring the placement, retrieve the API details to share with your IT team for integration:

1. Access the API Info: In the overview of the Audience API placements, locate the Actions column and click on the API Info icon.

2. Details Provided:

   • API Endpoint URL: The URL to access the Audience API.

   • User Identifiers: Instructions for using the Mapp Intelligence Ever ID or Customer ID.

   • Response Structure: Examples of the data returned for segments, User Categories, and metrics.

API Response Example

The API response provides structured data for the requested user, including segment membership, User Categories, and metrics.

Example API Request:

 GET https://<domain:port>/segments/v1/<accountId>/<placementId>?everId=<{{ eid }}>

Example API Response:

{
  "segments": [
    {
      "id": "123",
      "name": "High Value Customers",
      "isMember": true
    }
  ],
  "userCategories": [
    {
      "id": "456",
      "name": "Subscriber Status",
      "value": "Premium"
    }
  ],
  "metrics": [
    {
      "id": "789",
      "name": "Engagement",
      "value": "High"
    }
  ]
}

Find more details here: Audience REST API - Get Started