HeadSpin Documentation

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 https://<your_api_token>@api-dev.headspin.io/v0/devices/keys

The complete list is also included below.

Key Description Examples
host or hostname The host the target devices are on proxy-us-mvo-4.headspin.io
device_type The operating system android , ios
device_id The devices's device_id attribute 354013070326306, 2148038b48797464278f165acbb9140874b99a47
serial The device's serial number C6KR3359GRY5, 2ad32118
phone_imei The device's IMEI number 355696074827912
device_state The status of the device in HeadSpin's system online, offline, disconnected
operator If the device has a SIM card, this is the name of the carrier. Otherwise it is none sprint, verizon
phone_iccid If the phone has a SIM card, this is the ICCID number of the SIM card 89011200002039798496
phone_number If the device has a SIM card, this is the phone number of the SIM card. Otherwise it is none +1-669-600-7556, 6504441991
phone_network If the device has a mobile connection, this is the mobile network standard LTE, UMTS, unknown
network_type Whether a wifi or mobile connection is available to the device wifi, mobile
network_subtype If a mobile connection is available to the device, this is the connection provider. Otherwise it is the empty string '' LTE 700
network_connected Whether the device is connected to the internet, either through wifi or a mobile connection true or false
network_failover Whether the device's connection has failover capability (e.g. wifi to mobile) true or false
network_roaming Whether roaming is enabled on the device true or false
manufacturer The manufacturer of the device apple, samsung, lge
model The device model iPhone 6, Nexus 5X, SM-G900P
os_version The operating system's version number 8.0.0, 12
abi Which version of the ABI (Application Binary Interface) the device uses arm64-v8a
sdk Which API/NDK release the device uses. 23, 27
display_width The width of the device's display, in pixels 1080
display_height The height of the device's display, in pixels 1920
display_rotation Whether the device is in portrait or landscape mode 0 if portrait, 1 if landscape
display_secure true or false
display_size The diagonal size of the display screen, in inches 5.20073, 4.97125
display_xdpi The device screen's pixels per inch in the x dimension 422.03
display_ydpi The device's screen's pixels per inch in the y dimension 424.069
battery_health The device's battery health status good
battery_source Whether the battery is charged through an ac or a usb connection ac, usb
battery_status full
battery_level The battery level, in percentage 100.0
battery_temp The temperature of the battery 37.0
battery_voltage The battery's voltage 4.35
notes Any user-written note for the device
timestamp The current timestamp on the device, in UNIX time 1556662818.377

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 Selector Object Devices
{"os": "ios", "host": "proxy-us-sf-2.headspin.io"} iOS devices on host proxy-us-sf-2.headspin.io
{"os": "ios", "manufacturer": "samsung"} Samsung devices that run on iOS. Since all Samsung devices run on Android, this selector will not return any device.

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 https://<your_api_token>@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:

Operator Description Example Example Explanation
(space) or + or adjacent and device_type:ios host:*-us-la-*, or device_type:ios+host:*-us-la-* All iOS devices in us-la
, or device_id:DV3TQ,device_id:7d243b Devices with id DV3TQ or 7d243b
[...] context carrier:[nextel,oi] Devices whose carrier is Nextel or Oi
! not !host:*-jp-tyo-* Devices on hosts except jp-tyo
<, <=, >, >= comparisons os_version:>=5.* means versions 5.x and greater Devices with OS version 5.x and greater

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 'https://<your_api_token>@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-*"}



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.