Version 1.0 / January 2016
Use this API to create a set of device models to later be targeted by or excluded from a campaign:
https://api.applovin.com/devices/command
The following table briefly describes each command in this API:
create |
creates a new device list |
list |
lists the current device lists or the defined devices on a particular list |
append |
adds new devices to an existing list |
delete |
deletes a given device list |
deleteDevices |
removes given devices from a specific list |
Authentication:
This API requires that you add an API key as a query parameter (api_key) in the request:
https://api.applovin.com/devices/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 no Management Key is visible, 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 device list ID that you 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 a device list is for you to create an empty list. To create a new list, make an HTTP request to:
https://api.applovin.com/devices/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 a JSON-formatted response:
| Name | Type | Description |
|---|---|---|
device_list_id |
String | ID of the device list |
Example Request:
curl "https://api.applovin.com/devices/create?name=My%20Devices&api_key=API_KEY"
Example Response:
{"device_list_id" : "fce0b41a0849706bd0fbbe181e61f419"}
list
To get a list of all the current device lists, make an HTTP request to the list API.
https://api.applovin.com/devices/list?api_key=API_KEY
Response:
The response is a JSON-formatted response:
| Name | Type | Description |
|---|---|---|
code |
int | 200 for success |
device_lists |
List of Objects | a list of objects containing information about a device list |
device_list_id |
String | ID of the list |
name |
String | name of the list |
description |
String | description of the list |
device_count |
Long | number of devices that are part of the list |
count |
Long | number of lists returned |
Example Request:
curl "https://api.applovin.com/devices/list?api_key=API_KEY"
Example Response:
{
"code": 200,
"device_lists": [
{
"device_list_id": "dab2d1297d35592597b0eee016e92baa",
"name": "List Test",
"description": "Test Custom Device List",
"device_count": 3
}
],
"count": 1
}
list (with device list ID)
To get the list of all devices in a specified device list, make an HTTP request to the list API with a device_list_id parameter:
https://api.applovin.com/devices/list?api_key=API_KEY&device_list_id=DEVICE_LIST_ID
Query Params:
| Name | Type | Description | Required |
|---|---|---|---|
device_list_id |
String | ID of the device list returned from the create API | yes |
Response:
The response is a JSON-formatted response:
| Name | Type | Description |
|---|---|---|
code |
int | 200 for success |
devices |
List of Objects | a list of objects containing all devices in the list |
device |
String | device name |
count |
Long | number of devices that are part of the list |
Example Request:
curl "https://api.applovin.com/devices/list?api_key=API_KEY&device_list_id=fce0b41a0849706bd0fbbe181e61f419"
Example Response:
{
"code": 200,
"devices": [
{
"device":"SM-G900F"
},
{
"device":"SM-G900FD"
}
],
"count": 2
}
append
To append devices to an existing list, make an HTTP POST request to:
https://api.applovin.com/devices/append?api_key=API_KEY&device_list_id=DEVICE_LIST_ID
NOTE: The device names must be a specific format. You can see the format that this API expects here.
Query Params:
| Name | Type | Description | Required |
|---|---|---|---|
device_list_id |
String | ID of the device list returned from the create or list API | yes |
Post Body:
The append API accepts a newline-separated list of IDs in a POST request:
| Name | Type | Description | Required |
|---|---|---|---|
| List of devices | List of Strings | a newline-separated list of devices | yes |
Response:
The response is a JSON-formatted response:
| Name | Type | Description |
|---|---|---|
device_list_id |
String | ID of the device list |
processed_devices |
Integer | number of valid devices in this request |
failed_devices |
Integer | number of invalid devices in this request |
Example Request:
curl -X POST --data-binary @devices.txt "https://api.applovin.com/devices/append?device_list_id=DEVICE_LIST_ID&api_key=API_KEY"
Where the contents of the file devices.txt is:
SM-J100H HUAWEI Y520-U03
Example Response:
{ "device_list_id" : “dab2d1297d35592597b0eee016e92baa”, "processed_devices" : 2, "failed_devices" : 0 }
delete
To delete a device list, make an HTTP request to:
https://api.applovin.com/devices/delete?api_key=API_KEY&device_list_id=DEVICE_LIST_ID
Query Params:
| Name | Type | Description | Required |
|---|---|---|---|
device_list_id |
String | ID of the device list returned from the create or list API |
yes |
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/devices/delete?device_list_id=DEVICE_LIST_ID&api_key=API_KEY"
deleteDevices (Remove devices from a list)
To delete devices from an existing list, make an HTTP POST request to:
https://api.applovin.com/devices/deleteDevices?api_key=API_KEY&device_list_id=DEVICE_LIST_ID
Query Params:
| Name | Type | Description | Required |
|---|---|---|---|
device_list_id |
String | ID of the device list returned from the create or list API |
yes |
Post Body:
The delete devices API accepts a newline-separated list of IDs in a POST request:
| Name | Type | Description | Required |
|---|---|---|---|
| List of devices | List of Strings | a newline-separated list of devices | yes |
Response:
The response is a JSON-formatted response:
| Name | Type | Description |
|---|---|---|
device_list_id |
String | ID of the device list |
processed_devices |
Integer | number of devices deleted from the list in this request |
failed_devices |
Integer | number of invalid devices in this request |
Example Request:
curl -X POST --data-binary @devices.txt "https://api.applovin.com/devices/deleteDevices?device_list_id=DEVICE_LIST_ID&api_key=API_KEY"
Where the contents of the file devices.txt is:
SM-J100H HUAWEI Y520-U03
Example Response:
{ "device_list_id" : “dab2d1297d35592597b0eee016e92baa”, "processed_devices" : 2, "failed_devices" : 0 }
Targeting Campaigns to a Device List
Once you create a device list and associate devices with it, it will appear as an option in the Custom Devices section of the Edit Targets page for all campaigns.
