This API is deprecated. Please contact your account manager if you have questions.
Version 3.0 / March 2015
Use the Audience API 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 replaces 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 to the request as a query parameter 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 indicates errors with HTTP status codes:
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 JSON-formatted:
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 endpoint.
https://api.applovin.com/audiences/list?api_key=API_KEY
Response:
The response is JSON-formatted:
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 who 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 Parameters:
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 JSON-formatted:
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 Parameterss:
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 JSON-formatted:
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 erndpoint.
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
- You cannot remove individual users from an audience, but you can limit their eligibility to 0 seconds, which effectively removes them. To do this, make an append call with ttl_seconds=0.
- API Timeouts
- Requests time out after about 100 seconds. Depending on your connection speed and conditions on AppLovin’s end, this requires that you batch uploads into chunks of ~100k users. AppLovin recommends that you build batch-retry logic into scripts that interact with this API.
- Targeting a Campaign to an Audience
- After you create an audience and associate IDs with it, it appears 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.