Audience API Setup
Contents
Endpoint
All audience building requests are processed by endpoints with domain:
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
id (string) -- A unique id for the request. Typically a UUID
timestamp_ms (integer) -- Unix time in milliseconds
api_key (string) -- Account-specific API key
audience_id (integer) -- Unique identifier for the audience
audience_name (string) -- Name for the audience
action (string) -- One of the values in (add, update, remove)
audience_description (string) -- (Optional) Description of the audience
Example Request
Response JSON Object
status (string) -- Fixed to "ok" for successful responses
id (string) -- A unique id for the response
timestamp_ms (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
id (string) -- A unique id for the request. Typically a UUID
timestamp_ms (integer) -- Unix time in milliseconds
api_key (string) -- Account-specific API key
audience_id (integer) -- Unique identifier for the audience to update
action (string) -- (Optional) One of the values in (add, remove). Defaults to add.
identities (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.
properties (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.
attributes (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.
attribute_actions (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
status (string) -- Fixed to "ok" for successful responses
id (string) -- A unique id for the response
timestamp_ms (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.
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
api_key (string) -- API key for an account
Example URL
https://encore.aarki.com/dsp/api/validation/account?api_key=APIKEY123
Request JSON Object
api_key (string) -- API key for an account
Response JSON Object
status (string) -- "ok" if the API key is valid, "error" otherwise
message (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
api_key (string) -- Account-specific API key
audience_id (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
api_key (string) -- Account-specific API key
audience_id (integer) -- Identifier for the audience to be checked
Response JSON Object
status (string) -- "ok" if the API key is valid and the audience is registered with that API key, "error" otherwise
message (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
data (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.
Last updated