---
title: "Audience API"
slug: "audience-api"
updated: 2024-12-12T14:41:20Z
published: 2024-12-12T14:41:20Z
canonical: "docs.mapp.com/audience-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

Find more information about user identifiers on this page: [User-Centric Tracking (1): An introduction](/v1/docs/user-centric-tracking-1-an-introduction)
  - **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.
- **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:**

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

**Example API Response:**

```json
{
  "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](/v1/docs/audience-rest-api-get-started)

## Related

- [Audience REST API - Get Started](/audience-rest-api-get-started.md)
- [Using the Audience API](/using-the-audience-api.md)