Search for devices:

POST /devices/actions/query

Find devices by property values. Returns an array of all matching device resources.

See also:
Search Devices

Uses and Requirements

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/cc/v1/devices/actions/query

Resource Path and Query Parameters

None.

Header Parameters

The request header must contain a current ThingSpace authorization token and a current VZ-M2M session token, and must set the content-type to JSON.

 

Property Name Data Type Description
Authorization
required		 string HTTP Authorization request header containing a valid ThingSpace Bearer token.
VZ-M2M-Token
required		 string A valid session token returned by a Connectivity Management API POST /session/login request using the account’s UWS credentials.
Content-Type
required		 string Must be application/json.

Request Body

The request body specifies fields and values to match.

Property Name Data Type Description
accountidentifier
required		 JSON object The ID of the authenticating billing account, in the format {"billingaccountid":"1234567890-12345"}.
$selection
optional		 JSON object A comma-separated list of properties and comparator values to match against devices in the ThingSpace account. See Working with Query Filters for more information. If the request does not include $selection, the response will include all devices to which the requesting user has access.

Example Request

Find a device with a specific IMEI

curl POST https://thingspace.verizon.com/api/cc/v1/devices/actions/query \
  -H 'Authorization: Bearer 021833fbee3e118019f67777e028067f' \
  -H 'VZ-M2M-Token: f1ffff45-ed4c-4db0-a98c-a371afe23b6a' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountidentifier": {"billingaccountid":"1223334444-00001"},
    "resourceidentifier": {"imei": 159495694333703}
  }'

Find all device that were created after 12/1/2018

curl POST https://thingspace.verizon.com/api/cc/v1/devices/actions/query \
  -H 'Authorization: Bearer 021833fbee3e118019f67777e028067f' \
  -H 'VZ-M2M-Token: f1ffff45-ed4c-4db0-a98c-a371afe23b6a' \
  -H 'Content-Type: application/json' \
  -d '{
  "accountidentifier": {"billingaccountid":"1223334444-00001"},
  "$selection": {"createdon gt": "2018-12-01"}
  }'

Success Responses

Status 200

A success response includes an array of all matching devices. Each device includes the full device resource definition.

Property Name Data Type Description
billingaccountid string Billing account ID of the resource.
createdon string, date-time The date the resource was created.
description string Description of the device.
id string, UUID ThingSpace unique ID for the device that was added.
iccid string Cellular SIM card identifier.
imei string 4G hardware device identifier.
kind string Identifies the resource kind.
lastupdated string, date-time The date the resource was last updated.
msisdn string Telephone number of a cellular device.
name string Name of the device.
providerid string, UUID The device’s service provider.
refid string The value of the refidtype identifier.
refidtype string, enum The device identifier type used to refer to this device.
serial string Device serial number.
state string, enum Service state of the device.
tagids array, UUIDs UUIDs of tag resources that are applied to this device.
version string, UUID Version of the underlying schema resource.
versionid string, UUID The version of the resource.

Example Success Response

[
  {
    "billingaccountid": "1223334444-00001",
    "createdon": "2018-12-19T06:45:41.496Z",
    "eventretention": 90,
    "iccid": "20332350053095597842",
    "id": "64612cb3-3685-6dad-fd2b-ea1adeb5a269",
    "imei": 320778042285497,
    "kind": "ts.device",
    "lastupdated": "2018-12-19T06:45:41.508Z",
    "providerid": "8a314f07-849e-6568-e3c1-8381c1f61bfc",
    "refid": "20332350053095597842",
    "refidtype": "iccid",
    "state": "registered",
    "version": "1.0",
    "versionid": "b3cdaddb-0359-11e9-aba2-02420a4e1b0a"
  },
  {
    "billingaccountid": "1223334444-00001",
    "createdon": "2018-12-20T18:42:23.548Z",
    "description": "Monitor frozen fish during shipment",
    "eventretention": 90,
    "iccid": "89148000004197486411",
    "id": "0481cf95-e3b1-63eb-eb18-43bf717156cb",
    "imei": 864508030147323,
    "kind": "ts.device.cHeAssetTracker",
    "lastupdated": "2018-12-20T18:42:23.688Z",
    "name": "Fish Monitor",
    "providerid": "9dfcfa69-a1c8-4eae-8611-b282646bb113",
    "qrcode": "864508030147323",
    "refid": "864508030147323",
    "refidtype": "imei",
    "services": [
        "configuration"
    ],
    "state": "ready",
    "version": "1.0",
    "versionid": "fd835cc9-0486-11e9-a7da-02420a481608"
  }
]

Failure Responses

Status 4xx

All error messages are returned in this format:

{
  "error": "error code string",
  "error_description": "error message string",
  "cause": "further explanation"
}

Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.