> For the complete documentation index, see [llms.txt](https://help.rzr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rzr.com/readme/audience-sharing-setup/audience-api-setup.md).

# Audience API Setup

### Contents <a href="#fh31xmrmdm6r" id="fh31xmrmdm6r"></a>

* [Endpoint](#fh31xmrmdm6r-1)
* [Audience Subscription Request](#audience-subscription-request)
* [Audience Membership Change Request](#audience-membership-change-request)
* [API Limits](#api-limits)
* [Validation Endpoints](#validation-endpoints)
* [Account Validation](#account-validation)
* [Audience Validation](#audience-validation)

***

### Endpoint <a href="#fh31xmrmdm6r" id="fh31xmrmdm6r"></a>

All audience building requests are processed by endpoints with domain:

<http://audiences.aarki.net/>

The endpoints accept a JSON object passed in the request body, encoded in application/json.

**The following types of requests are supported:**

* Audience Subscription Request
* Audience Membership Change Request

The endpoints also support the https protocol, with a response time overhead.

***

### Audience Subscription Request

**`POST /audience`**

Audience Subscription Request is used to notify creation of a new audience, removal of an audience, or an update to an audience. Complete audience removal can take some time as all connected campaigns have to be disabled.

**Request JSON Object**

<mark style="color:red;">`id`</mark> (string) -- A unique id for the request. Typically a UUID

<mark style="color:red;">`timestamp_ms`</mark> (integer) -- Unix time in milliseconds

<mark style="color:red;">`api_key`</mark> (string) -- Account-specific API key

<mark style="color:red;">`audience_id`</mark> (integer) -- Unique identifier for the audience

<mark style="color:red;">`audience_name`</mark> (string) -- Name for the audience

<mark style="color:red;">`action`</mark> (string) -- One of the values in (add, update, remove)

<mark style="color:red;">`audience_description`</mark> (string) -- *(Optional)* Description of the audience

Example Request

```
{
  "id": "d129cb4e-1023-477f-b4db-b603281ec436",
  "timestamp_ms": 1495690639334,
  "api_key": "APIKEY123",
  "audience_id": 6789,
  "audience_name": "Example Audience",
  "action": "add"
}
```

**Response JSON Object**

<mark style="color:red;">`status`</mark> (string) -- Fixed to "ok" for successful responses

<mark style="color:red;">`id`</mark> (string) -- A unique id for the response

<mark style="color:red;">`timestamp_ms`</mark> (integer) -- Unix time in milliseconds

***

### Audience Membership Change Request

**`POST /membership`**

Audience Membership Change Request is used to notify addition or removal of device identifiers to or from an audience, or for sharing additional user information.

**Request JSON Object**

<mark style="color:red;">`id`</mark> (string) -- A unique id for the request. Typically a UUID

<mark style="color:red;">`timestamp_ms`</mark> (integer) -- Unix time in milliseconds

<mark style="color:red;">`api_key`</mark> (string) -- Account-specific API key

<mark style="color:red;">`audience_id`</mark> (integer) -- Unique identifier for the audience to update

<mark style="color:red;">`action`</mark> (string) -- *(Optional)* One of the values in (add, remove). Defaults to add.

<mark style="color:red;">`identities`</mark> (jsonobject) -- *(Optional)* A dictionary having identifier type as keys, and lists of identifiers as values. All identifier lists should have the same length. Values in each identifier list can either be singular values, or lists of singular values. Device identities can be sent in one of gaid or idfa identifier fields. Customer ids, player ids, and similar identifiers can also be sent through identities field. Empty strings will be treated as null values.

<mark style="color:red;">`properties`</mark> (jsonobject) -- *(Optional)* A dictionary with property names as keys, and lists of property values as values. All property lists should have the same length, and be in the same order as each of identities lists. Values in each property list can either be singular values, or lists of singular values. Observed user ips, device models, operating system versions, and device languages can be sent as properties. Empty strings will be treated as null values.

<mark style="color:red;">`attributes`</mark> (jsonobject) -- *(Optional)* A dictionary having attribute names as keys, and lists of attribute values in the same order as each of identities lists as values. Strings are preferred for decimals. Empty strings for attributes with upsert and append attribute actions will be treated as null values.

<mark style="color:red;">`attribute_actions`</mark> (jsonobject) -- *(Optional)* A dictionary mapping attribute names to action, which can have the following values: upsert (Default), append, extend (append all elements in a list), delete.

**Response JSON Object**

<mark style="color:red;">`status`</mark> (string) -- Fixed to "ok" for successful responses

<mark style="color:red;">`id`</mark> (string) -- A unique id for the response

<mark style="color:red;">`timestamp_ms`</mark> (integer) -- Unix time in milliseconds

Example Request:

Please note that all identities, properties, and attributes have lists of the same length as values, as each index of these lists corresponds to one user.

```
{
  "id": "ed60e202-bc70-41f2-bda1-dfbc2d4402d7",
  "timestamp_ms": 1495690897322,
  "api_key": "APIKEY123",
  "audience_id": 6789,
  "action": "add",
  "identities": {
    "customer_id": ["cid_1", "cid_2", "cid_3"],
    "player_id": ["pid_1", "", ""],
    "idfa": [
      ["00000000-1111-2222-3333-444444444444", "11111111-1111-2222-3333-444444444444"],
      ["22222222-1111-2222-3333-444444444444"],
      []
    ]
  },
  "properties": {
    "user_ip": [["1.2.3.4", "1.2.3.5"], [], ["2001:db8:85a3::"]],
    "device_os_version": ["13.1", "13.3.1", "14.1"],
    "device_model": ["iPhone 5s", "iPhone 6", "iPhone XS"],
    "device_language": ["", "en-US", "en"]
  },
  "attributes": {
    "favourite_character": ["x", "x", "z"],
    "new_achievements": [["l1", "l2"], [], ["l5"]],
    "daily_progress": [12, 20, 6],
    "gold_coins": ["", "", ""],
    "implicit_upsert_attr": ["", "a", "b"]
  },
  "attribute_actions": {
    "favourite_character": "upsert",
    "new_achievements": "extend",
    "daily_progress": "append",
    "gold_coins": "delete"
  }
}
```

**User Breakdown Example**

In this example, there are three users:

**FIRST USER**

* **Identities:**

`"idfa": ["00000000-1111-2222-3333-444444444444", "11111111-1111-2222-3333-444444444444"]`

`"customer_id": "cid_1", "player_id": "pid1_1"`

* **Properties:**

`"user_ip": ["1.2.3.4", "1.2.3.5"], "device_os_version": "13.1", "device_model": "iPhone 5s"`

* **Attributes:**

`"favourite_character": "x", "new_achievements": ["l1", "l2"], "daily_progress": 12`

**SECOND USER**

* **Identities:**

`"idfa": ["22222222-1111-2222-3333-444444444444"], "customer_id": "cid_2"`

* **Properties:**

`"device_os_version": "13.3.1", "device_model": "iPhone 6", "device_language": "en-US"`

* **Attributes:**

`"favourite_character": "x", "daily_progress": 20, "implicit_upsert_attr": "a"`

**THIRD USER**

* **Identities:**

`"customer_id": "cid_3"`

* **Properties:**

`"user_ip": ["2001:db8:85a3::"], "device_os_version": "14.1", "device_model": "iPhone XS", "device_language": "en"`

* **Attributes:**

`"favourite_character": "z", "new_achievements": ["l5"], "daily_progress": 6, "implicit_upsert_attr": "b"`

***

### API Limits

The current version of the RZR Audience API has the following limits:

**Audience Membership Change Requests**

* Each request can contain at most 10,000 devices. That is, the length of values in each field of identities should not exceed 10,000.
* Total size of each request should not exceed 1 megabyte.

***

### Validation Endpoints

In addition to the audience building endpoints, there are the following validation endpoints located at:

<https://encore.aarki.com/dsp/api/validation/>

* Account Validation
* Audience Validation

Both endpoints accept parameters in either query string or JSON body.

***

### Account Validation

**`GET or POST /account`**

Account validation endpoint is used to check if a given API key is registered with a valid account.

**Query Parameters**

<mark style="color:red;">`api_key`</mark> (string) -- API key for an account

**Example URL**

<https://encore.aarki.com/dsp/api/validation/account?api_key=APIKEY123>

**Request JSON Object**

<mark style="color:red;">`api_key`</mark> (string) -- API key for an account

```
{ "api_key": "APIKEY123" }
```

**Response JSON Object**

<mark style="color:red;">`status`</mark> (string) -- "ok" if the API key is valid, "error" otherwise

<mark style="color:red;">`message`</mark> (string) -- *(Optional)* Present only in case of error. Fixed to "Wrong Api Key" if the API key is invalid.

***

### Audience Validation

**`GET or POST /audience`**

Audience validation endpoint is used to check if a given audience is registered with a given API key. It also returns the size of the audience in case of success.

**Query Parameters**

<mark style="color:red;">`api_key`</mark> (string) -- Account-specific API key

<mark style="color:red;">`audience_id`</mark> (integer) -- Identifier for the audience to be checked

**Example URL**

<https://encore.aarki.com/dsp/api/validation/audience?api_key=APIKEY123&audience_id=6789>

**Request JSON Object**

<mark style="color:red;">`api_key`</mark> (string) -- Account-specific API key

<mark style="color:red;">`audience_id`</mark> (integer) -- Identifier for the audience to be checked

```
{ "api_key": "APIKEY123", "audience_id": 6789 }
```

**Response JSON Object**

<mark style="color:red;">`status`</mark> (string) -- "ok" if the API key is valid and the audience is registered with that API key, "error" otherwise

<mark style="color:red;">`message`</mark> (string) -- *(Optional)* "Wrong Api key" if the API key is invalid; "Wrong Audience id" if the audience id is not registered with the given API key or the audience has been deleted

<mark style="color:red;">`data`</mark> (jsonobject) -- *(Optional)* Present in case of success. A dictionary containing a single key "size" and the size of the audience as its value.

***

This guide covers everything you need to send audiences to RZR directly via API — including endpoints, request types, parameters, and validation.

If you need help with setup, reach out to your **RZR Account Manager** or **Account Coordinator** for assistance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.rzr.com/readme/audience-sharing-setup/audience-api-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.