Version 1.0 / March 2017
Advertisers use this API to create a set of apps to later be targeted by or excluded from a campaign. This replaces the old whitelist/blacklist API that will soon be deprecated.
Targeting APIs
To use these APIs, send an HTTP request to the following URL:
https://api.applovin.com/applists/command
The following table briefly describes the various command values and their purposes:
Command | Description |
---|---|
create | creates a new app list |
list | displays the current apps-lists or the defined apps |
append | adds new apps to an existing list |
delete | deletes a given app list |
deleteApps | removes given apps from a specific list |
Authentication
This API requires that you include an API key as the value of a query parameter (api_key) in the request. 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, please open a ticket here and request one be generated for you. Add this key to your API request in the following way:
https://api.applovin.com/applists/command?api_key=API_KEY
Errors
This API indicates errors by means of HTTP status codes:
HTTP Response Code |
Description |
---|---|
200 |
Success. |
400 |
The request was not formatted properly; it was missing data or had invalid data. |
403 |
Authentication failed. Check the validity of the API Key. |
404 |
The App List ID specified does not exist. |
406 |
For create, an active list with the same name exists already. |
500 |
Service Unavailable. |
create
The first step when you submit an app list is to create an empty list. To create a new list, make an HTTP request to
https://api.applovin.com/applists/create?api_key=API_KEY&name=LIST_NAME
The create API accepts the following fields passed as URL-encoded query parameters
Name | Type | Description | Required |
---|---|---|---|
name | String | name of the list | yes (must be alphanumeric, _-+, or URL-encoded space) |
description | String | description of the list | no |
Response:
The response is JSON-formatted:
Name | Type | Description |
---|---|---|
app_list_id |
String | ID of the audience |
Example Request:
curl "https://api.applovin.com/applists/create?name=High%20Perfoming%20Apps&api_key=API_KEY"
Example Response:
{"app_list_id" : "fce0b41a0849706bd0fbbe181e61f419"}
list
To get a list of all of the current app lists, make an HTTP request to the list endpoint:
https://api.applovin.com/applists/list?api_key=API_KEY
Response:
The response is JSON-formatted:
Name | Type | Description |
---|---|---|
code |
Integer | 200 for success |
app_lists |
List of Objects | a list of objects containing information about an app list |
app_list_id |
String | ID of the list |
name |
String | name of the list |
description |
String | description of the list |
app_count |
Long | number of apps that are part of the list |
count |
Long | number of lists returned |
Example Request:
curl "https://api.applovin.com/applists/list?api_key=API_KEY"
Example Response:
{ "code": 200, "app_lists": [ { "app_list_id": "dab2d1297d35592597b0eee016e92baa", "name": "High Performing Apps", "description": "Apps that exceed our ROAS goals", "app_count": 3 } ], "count": 1 }
list (with an app list ID defined)
To get the list of all apps in a specified app list, make an HTTP request to the list endpoint with an app_list_id parameter:
https://api.applovin.com/applists/list?api_key=API_KEY&app_list_id=APP_LIST_ID
Query Params:
Name | Type | Description | Required |
---|---|---|---|
app_list_id | String | ID of the app list returned from the create or list endpoint | yes |
Response:
The response is JSON-formatted:
Name | Type | Description |
---|---|---|
code |
Integer | 200 for success |
apps |
List of Objects | a list of objects containing all apps in the list |
application |
String | external application ID |
count |
Long | number of apps that are part of the list |
Example Request:
curl "https://api.applovin.com/applists/list?api_key=API_KEY&app_list_id=fce0b41a0849706bd0fbbe181e61f419"
Example Response:
{ "code": 200, "apps": [ { "application":"a0849706bda0849706bd" }, { "application":"4326af2346b2l46e2346" } ], "count": 2 }
append
To append apps to an existing list, make an HTTP POST request to:
https://api.applovin.com/applists/append?api_key=API_KEY&app_list_id=APP_LIST_ID
Query Parameters:
Name | Type | Description | Required |
---|---|---|---|
app_list_id | String | ID of the app list returned from the create or list endpoint | yes |
Post Body:
The append endpoint accepts a newline-separated list of IDs in a POST request:
Name | Type | Description | Required |
---|---|---|---|
List of apps | List of Strings | a newline-separated list of external application IDs | yes |
Response:
The response is JSON-formatted:
Name | Type | Description |
---|---|---|
app_list_id |
String | ID of the app list |
processed_apps |
Integer | number of valid apps in this request |
failed_apps |
Integer | number of invalid apps in this request |
Example Request:
curl -X POST --data-binary @apps.txt "https://api.applovin.com/applists/append?app_list_id=APP_LIST_ID&api_key=API_KEY"
Where the contents of the file apps.txt is:
a0849706bda0849706bd 4326af2346b2l46e2346
Example Response:
{ "app_list_id" : “dab2d1297d35592597b0eee016e92baa”, "processed_apps" : 2, "failed_apps" : 0 }
delete
To delete an app list, make an HTTP request to
https://api.applovin.com/applists/delete?api_key=API_KEY&app_list_id=APP_LIST_ID
Query Parameters:
Name | Type | Description | Required |
---|---|---|---|
app_list_id | String | ID of the app list returned from the create or list endpoint | yes |
Response:
There is no response body for the delete endpoint. On success it returns HTTP Response code 200.
Example Request:
curl "https://api.applovin.com/applists/delete?app_list_id=APP_LIST_ID&api_key=API_KEY"
deleteApps (remove apps from a list)
To delete apps from an existing list, make an HTTP POST request to:
https://api.applovin.com/applists/deleteApps?api_key=API_KEY&app_list_id=APP_LIST_ID
Query Parameters:
Name | Type | Description | Required |
---|---|---|---|
app_list_id | String | ID of the app list returned from the create or list endpoint | yes |
Post Body:
The append endpoint accepts a newline-separated list of IDs in a POST request.
Name | Type | Description | Required |
---|---|---|---|
List of apps | List of Strings | a newline-separated list of external application IDs | yes |
Response:
The response is JSON-formatted:
Name | Type | Description |
---|---|---|
app_list_id |
String | ID of the app list |
processed_apps |
Integer | number of apps deleted from the list in this request |
failed_apps |
Integer | number of invalid apps in this request |
Example Request:
curl -X POST --data-binary @apps.txt "https://api.applovin.com/applists/deleteApps?app_list_id=APP_LIST_ID&api_key=API_KEY"
Where the contents of the file apps.txt is:
a0849706bda0849706bd 4326af2346b2l46e2346
Example Response:
{ "app_list_id" : “dab2d1297d35592597b0eee016e92baa”, "processed_apps" : 2, "failed_apps" : 0 }
Targeting Campaigns to an App List
Once an app list is created and has apps associated with it, it will appear as an option in the Application section of the Edit Targets page for all campaigns.