Search Devices

Search for devices:
POST /devices/actions/search

Search for devices by property values. Returns an array of all matching device resources, including the latest sensor values and configuration settings for each device.

See also:
Query Devices

Uses and Requirements

Request Components

HTTP Request

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

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 Body

Find a device with a specific ICCID

curl -X POST https://thingspace.verizon.com/api/cc/v1/devices/actions/search \
  -H 'Authorization: Bearer 16f6abbb55ce3980a82dd3a0c1d797af' \
  -H 'VZ-M2M-Token: dd483724-b734-4e13-b89a-15d254c310d9' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountidentifier": {"billingaccountid":"1223334444-00001"},
    "$selection": {"iccid": "89148000003499233389"}
  }'

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

curl -X POST https://thingspace.verizon.com/api/cc/v1/devices/actions/search \
  -H 'Authorization: Bearer 16f6abbb55ce3980a82dd3a0c1d797af' \
  -H 'VZ-M2M-Token: dd483724-b734-4e13-b89a-15d254c310d9' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountidentifier": {"billingaccountid":"1223334444-00001"},
    "$selection": {"createdon gt": "2018-12-31"}
  }'

Success Responses

Status 200

A success response includes an array of all matching devices. Each device includes the full device resource definition and the latest field (sensor) values.

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.
fields JSON object List of device sensors and their most recently reported values.
iccid string Cellular SIM card identifier.
id string, UUID ThingSpace unique ID for the device that was added.
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

[
  {
    "actions": {
      "configuration": {
        "configuration": {
          "Date": "2019-02-14T02:34:53.149140091Z",
          "State": "update"
        }
      }
    },
    "billingaccountid": "1223334444-00001",
    "createdon": "2019-01-05T00:14:35.547Z",
    "eventretention": 90,
    "fields": {
      "acceleration": {
        "x": "0.0277",
        "y": "-1.0334",
        "z": "-0.0134"
      },
      "battery": "95",
        "light": {
          "Threshold": "100",
          "ThresholdRange": "21699",
          "alarmType": "4",
          "sensorReading": "98"
        }
      },
      "humidity": "29",
      "light": "150",
      "location": {
        "latitude": "37.2314796",
        "longitude": "-119.4692153"
      },
      "orientation": {
        "motionInX": "268.0",
        "motionInY": "1.0",
        "motionInZ": "0.0"
      },
      "pressure": "888",
      "signalStrength": "-58",
      "temperature": "19.2"
    },
    "iccid": "89148000003499233389",
    "id": "8461f530-2e31-6e87-e357-6c38251d41d0",
    "imei": 864508030084799,
    "kind": "ts.device.cHeAssetTracker",
    "lastupdated": "2019-02-17T03:57:26.577Z",
    "providerid": "9dfcfa69-a1c8-4eae-8611-b282646bb113",
    "qrcode": "864508030084799",
    "refid": "864508030084799",
    "refidtype": "imei",
    "services": [
      "configuration"
    ],
    "state": "ready",
    "tagids": [
      "4d110e4f-7a7c-6b26-eaac-31cc34c6e1d4",
      "cd81ed16-18ae-6c7d-eaba-2883b0395387"
    ],
    "version": "1.0",
    "versionid": "238a7e2e-3268-11e9-91d6-02420a472210"
  },
  {
    "actions": {
      "configuration": {
        "configuration": {
          "Date": "2019-01-11T03:04:49.435931518Z",
          "State": "update"
        }
      }
    },
    "billingaccountid": "1223334444-00001",
    "createdon": "2019-01-09T00:00:48.387Z",
    "eventretention": 90,
    "fields": {
      "acceleration": {
        "x": "-0.0762",
        "y": "-0.0152",
        "z": "1.0864"
      },
      "battery": "1",
      "humidity": "38",
      "light": "0",
      "location": {
        "latitude": "32.8980026",
        "longitude": "-117.2033309"
      },
      "orientation": {
        "motionInX": "0.0",
        "motionInY": "4.0",
        "motionInZ": "0.0"
      },
      "pressure": "1012",
      "signalStrength": "-86",
      "temperature": "20.2"
    },
    "iccid": "89148000003499234933",
    "id": "44314312-3cbc-651d-fec4-286e0baa5182",
    "imei": 864508030027310,
    "kind": "ts.device.cHeAssetTracker",
    "lastupdated": "2019-01-11T03:04:49.436Z",
    "providerid": "9dfcfa69-a1c8-4eae-8611-b282646bb113",
    "qrcode": "864508030027310",
    "refid": "864508030027310",
    "refidtype": "imei",
    "services": [
      "configuration"
    ],
    "state": "ready",
    "version": "1.0",
    "versionid": "a8743c8a-154d-11e9-ba53-02420a401605"
  }
]

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.