Device Selectors API

Device Selectors

A wide range of devices, locations and carriers is available through HeadSpin. To help you identify devices with a specific combination of characteristics, HeadSpin provides a powerful Selector syntax that can be used with the HeadSpin API calls.

Selector Keys

Selectors work by finding devices matching any number of key : values pairs, such as <code class="dcode">device_type:ios</code> or <code class="dcode">manufacturer:samsung</code>. The values are not case sensitive. The list of all selector keys is available through the Devices API:

curl -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/devices/keys

The complete list is also included below.

HeadSpin Selectors can be written as JSON objects (often in the body of API POST requests) or query parameters (often in API GET requests).

Selectors as a JSON Object

Selectors can be written as JSON objects where each key is a Selector key. The selector will find devices matching all provided key : value pairs (i.e. the keys : values pairs are and'ed together).

For example:

JSON selectors are used in many API routes with a request body (e.g. POST requests). Below is an example of a selector used in an API call to lock a device.

curl -X POST -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/devices/lock --data '{"hostname":"proxy-us-mvo-2.headspin.io", "model": "iPhone 6"}' -H "Content-Type: application/json"

Selectors as a query parameter

Sometimes Selectors cannot be written as a JSON object. This often happens in API GET requests, where the request body won't be procesed. In those cases, the Selector can be expressed in the URL as a query parameter. This option also allows more complex ways to combine selector keys, using not only the default <code class="dcode">and</code> operation as seen in JSON selector objects but also <code class="dcode">or</code>, <code class="dcode">not</code>, etc. A list of available operations is provided below:

Below is an example of a Selector query in an API call. This call gives a list of Android devices available to you, has OS version 5.0 or greater, and not made by LGE.

curl -H "Authorization: Bearer <your_api_token>" 'https://api-dev.headspin.io/v0/adbm/os_version:>=5+manufacturer:!lge/devices' 

Selecting a Specific Device

If you'd like to use a specific device, you can use the <code class="dcode">device_id</code> or <code class="dcode">serial</code> selector keys. For example:<code class="dcode">{ "serial": "7d243b"}</code> or <code class="dcode">serial:7d243b</code>

Wildcards in Selectors

The selector strings may use the <code class="dcode">*</code> wildcards for more flexible matching.

For example:

{"host": "*-us-la-*"}

or

host:*-us-la-*

This Selector looks for devices in all hosts matching with the string <code class="dcode">-us-la-</code> anywhere in the hostname. If there many US-LA hosts available to you (e.g. <code class="dcode">proxy-us-la-0</code>, <code class="dcode">proxy-us-la-1...</code>), this Selector will match with devices in all these hosts.