Version 3.0 / March 2015
Use the Audience APIs to create a set of users who can later be targeted with a campaign. Create audiences by using Apple’s IDFA or Android’s advertising ID. To use this API, make HTTP requests to this URL:
https://api.applovin.com/audiences/command
The following table summarizes each command in this API:
create |
creates a new audience |
list |
lists the current audiences |
update |
updates the audience list with a new group of users (This will replace the existing user list for a given audience.) |
append |
adds new users to an existing audience |
delete |
deletes a given audience |
Authentication
All Audience Targeting APIs require that you add an API key as a query parameter in the request (api_key
):
https://api.applovin.com/audiences/command?api_key=API_KEY
You can find this Management Key (formerly called the Custom Audience Key) in the Keys tab of your account page. If the Management Key is not visible there, email AppLovin support at adsupport@applovin.com and one will be generated for you.
Errors
This API uses HTTP status codes to indicate errors:
HTTP Response Code | Description |
---|---|
200 | Success. |
400 | The request was not formatted properly, was missing data, or had invalid data. |
403 | Authentication failed. Check the validity of the API Key. |
404 | The audience ID you specified does not exist. |
406 | For create , an active audience with the same parameters exists already. |
500 | Service Unavailable. |
create
The first step when you submit a custom audience is for you to create an empty audience. To create a new audience, make an HTTP request to:
https://api.applovin.com/audiences/create?api_key=API_KEY
The create
API accepts the following fields, passed as URL-encoded query parameters:
Name | Type | Description | Required |
---|---|---|---|
name |
String | Name of the audience | yes (Must be alphanumeric, _-+ , or URL-encoded space) |
package_name |
String | Package name or bundle ID of the source app. | yes, if audience_type=retargeting |
platform |
Enum (android , ios ) |
Platform of the source app. Must be “android ” or “ios ”. |
yes |
description |
String | Description of the audience. | no |
audience_type |
Enum (ua , retargeting ) |
Type of audience. Defaults to retargeting . |
yes, if audience_type=ua |
Response:
The response is a JSON-formatted response:
Name | Type | Description |
---|---|---|
audience_id |
String | ID of the audience |
Example Request:
curl "https://api.applovin.com/audiences/create?name=My%20Audience%20Name&package_name=my.app.bundleId&platform=ios&api_key=API_KEY"
Example Response:
{"audience_id" : "fce0b41a0849706bd0fbbe181e61f419"}
list
To get a list of all the current audiences for a given user, make an HTTP request to the list
API.
https://api.applovin.com/audiences/list?api_key=API_KEY
Response:
The response is a JSON-formatted response:
Name | Type | Description |
---|---|---|
code |
int | 200 for success |
audiences |
List of Objects | a list of objects containing information about an audience |
audience_id |
String | ID of the audience |
name |
String | name of the audience |
package_name |
String | iTunes Id or package name of the source app |
platform |
Enum (android , ios ) |
platform of the source app (must be “android ” or “ios ”) |
description |
String | description of the audience |
user_count |
Long | number of users that are part of the audience |
count |
Long | number of audiences the user has |
Example Request:
curl "https://api.applovin.com/audiences/list?api_key=API_KEY"
Example Response:
{ "code": 200, "audiences": [ { "audience_id": "dab2d1297d35592597b0eee016e92baa", "name": "Custom Audience Test", "package_name": "Some package name", "platform": "ios", "description": "Test Custom Audience", "user_count": "10" } ], "count": 1 }
update
To upload a list of users to a given audience, use the update
API. If the audience already has an existing user list, this replaces that list with the list of users in the update API request.
To update an audience with a new user list make an HTTP POST
request to:
https://api.applovin.com/audiences/update?api_key=API_KEY&audience_id=AUDIENCE_ID&ttl_seconds=TTL_SECONDS
Query Params:
Name | Type | Description | Required |
---|---|---|---|
audience_id |
Long | ID of the audience returned from the create API |
yes |
ttl_seconds |
Long | seconds the users have to live (seconds until they expire); default is 365 days | no |
Post Body:
The update
API accepts a newline-separated list of IDs in a POST
request:
Name | Type | Description | Required |
---|---|---|---|
List of advertising ids | List of Strings | A newline-separated list of Apple’s IDFA or Android’s advertising ID. The IDs must be in UUID format. | yes |
Response:
The response is a JSON-formatted response:
Name | Type | Description |
---|---|---|
audience_id |
Long | ID of the audience |
num_valid_ids |
Integer | number of valid advertising IDs in the new audience list |
num_invalid_ids |
Integer | number of invalid advertising IDs in this request |
Example Request:
curl -X POST --data-binary @userIds.txt "https://api.applovin.com/audiences/update?audience_id=AUDIENCE_ID&ttl_seconds=2592000&api_key=API_KEY"
Where the contents of the file userIds.txt
is:
c77bbe4e-6a28-11e4-bcda-14109fdf9591 f601faf5-4a83-44d6-98ef-b67c24919d39
Example Response:
{ "audience_id" :“dab2d1297d35592597b0eee016e92baa”, "num_valid_ids" : 2, "num_invalid_ids" : 0 }
append
To add users to an existing audience, use the append
API. If the audience already has an existing user list, this appends the users to the list.
To append users to an audience with a new user list make an HTTP POST
request to:
https://api.applovin.com/audiences/append?api_key=API_KEY&audience_id=AUDIENCE_ID&ttl_seconds=TTL_SECONDS
Query Params:
Name | Type | Description | Required |
---|---|---|---|
audience_id |
Long | ID of the audience returned from the create API |
yes |
ttl_seconds |
Long | seconds the users have to live (seconds until they expire); default is 365 days | no |
Post Body:
The update
API accepts a newline-separated list of IDs in a POST
request:
Name | Type | Description | Required |
---|---|---|---|
List of advertising IDs | List of Strings | a newline-separated list of Apple’s IDFA or Android’s advertising ID; the IDs must be in UUID format | yes |
Response:
The response is a JSON-formatted response:
Name | Type | Description |
---|---|---|
audience_id |
Long | ID of the audience |
num_valid_ids |
Integer | number of valid advertising IDs in the new audience list |
num_invalid_ids |
Integer | number of invalid advertising IDs in this request |
Example Request:
curl -X POST --data-binary @userIds.txt "https://api.applovin.com/audiences/append?audience_id=AUDIENCE_ID&ttl_seconds=2592000&api_key=API_KEY"
Where the contents of the file userIds.txt
is:
c77bbe4e-6a28-11e4-bcda-14109fdf9591 f601faf5-4a83-44d6-98ef-b67c24919d39
Example Response:
{ "audience_id" : “dab2d1297d35592597b0eee016e92baa”, "num_valid_ids" : 2, "num_invalid_users" : 0 }
delete
To delete an audience make an HTTP request to:
https://api.applovin.com/audiences/delete?api_key=API_KEY&audience_id=AUDIENCE_ID
where AUDIENCE_ID is the ID returned from the create
API.
Response:
There is no response body for the delete
API. On success it returns HTTP Response code 200.
Example Request:
curl "https://api.applovin.com/audiences/delete?audience_id=AUDIENCE_ID&api_key=API_KEY"
Tips
- Deleting users from an audience without updating the full audience
- There is no way to remove individual users from an audience, but you can limit their eligibility down to 0 seconds, which effectively removes them. To do this, make an
append
call withttl_seconds=0
. - API Timeouts
- Requests timeout after about 100 seconds. Depending on your connection speed and conditions on our end, this will require that you batch uploads into chunks of ~100k users. We recommend building batch-retry logic into scripts that interact with this API.
- Targeting a Campaign to an Audience
- Once you create an audience and associate IDs with it, it will appear as an option in the Custom Audience section of the Edit Targets page for all eligible campaigns. An audience is eligible for a campaign if they share the same package name and platform, if the campaign type and audience type are retargeting; and if they share the same platform, if the campaign type and audience type are user acquisition.