This API is deprecated. Please contact your account manager if you have questions.
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 indicates errors by returning HTTP status codess:
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 endpoint 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 |
---|---|---|
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 endpoint.
https://api.applovin.com/devices/list?api_key=API_KEY
Response:
The response is JSON-formatted:
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 endpoint with a device_list_id parameter:
https://api.applovin.com/devices/list?api_key=API_KEY&device_list_id=DEVICE_LIST_ID
Query Parameters:
Name | Type | Description | Required |
---|---|---|---|
device_list_id | String | ID of the device list returned from the create endpoint | yes |
Response:
The response is JSON-formatted:
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
The device names must be a specific format. You can see the format that this API expects here.
Query Parameters:
Name | Type | Description | Required |
---|---|---|---|
device_list_id | String | ID of the device list returned from the create or list endpoints | yes |
Post Body:
The append endpoint 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 JSON-formatted:
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 Parameters:
Name | Type | Description | Required |
---|---|---|---|
device_list_id | String | ID of the device 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/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 Parameters:
Name | Type | Description | Required |
---|---|---|---|
device_list_id | String | ID of the device list returned from the create or list endpoint | yes |
Post Body:
The delete devices endpoint 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 JSON-formatted:
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.