Device Model Targeting API

  • Updated

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.

Example Postman Collection: