App List API

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 a query parameter (api_key) in the request:

https://api.applovin.com/applists/command?api_key=«management-key»

You can find this Management 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.

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=«management-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%20Performing%20Apps&api_key=«management-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=«management-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=«management-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 app list ID)

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=«management-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

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=«management-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=«management-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=«management-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=«management-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=«management-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=«management-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=«management-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.

Example Postman Collection

Download AppLovin App Lists Postman Collection