Specialized APIsSensor InsightsAPI Reference
Set device configuration
POST /dm/v1/devices/actions/set
Use this endpoint to configure a sensor.
Note: These examples are for Bluetooth Low Energy (BLE) and the RBS high precision tilt sensor.
Header Parameters
The request header must set the content-type to JSON, contain a current ThingSpace authorization token and a current VZ-M2M session token. For more details on how to get these tokens, visit Getting Started.
| Parameter Name | Data Type | Description |
|---|---|---|
| Authorization (required) | string | HTTP Authorization request header containing a valid Bearer token: Authorization: Bearer {token} |
| VZ-M2M-Token (required) | string | A valid session token returned by a Connectivity Management POST /session/login request. |
| Content-Type (required) | string | Must be application/json. |
HTTP Request
PATCH https://thingspace.verizon.com/api/dm/v1/devices/actions/set
Request Parameters
Note: All parameters are required unless marked (optional)
| Parameter | Data Type | Description |
|---|---|---|
| accountname | string | The numeric name of the account and must include leading zeros. |
| configuration | object | The configuration details and identifiers for the sensor. |
| deviceConfig | object | Configuration details specific to the technology of the sensor. This example is Bluetooth Low Energy or BLE. |
| dataMode | integer | The format of the data output. This varies by device and manufacturer. |
| manufacturerId | integer | A numeric ID of the manufacturer. |
| maxNumScan | integer | How frequently to scan the device. This varies by device and manufacturer. |
| minSigStr | integer | The minimum signal strength required to transmit (in Decibels or dB). |
| monitorPeriod | integer | The period of time to monitor the device. This varies by device and manufacturer. |
| moreManufId | array | Additional manufacturer information. |
| opMode | integer | Operation mode. This value varies by device and manufacturer. |
| reportOffset | integer | The ammount of time between a sensor reading and data being reported. This varies by device and manufacturer. |
| reportPeriod | integer | When the sensor sends data. This varies by device and manufacturer. |
| reportType | integer | The type of report sent by the device. This varies by device and manufacturer. |
| scanDuration | integer | The ammount of time spent polling a device. This varies by device and manufacturer. |
| resourceidentifier | object | Details about the device being configured. |
| deveui | string | The unique EUI64 address of the device. |
| deviceid | string | The UUID of the device. This is assigned to the device at Onboarding. |
| esn | integer | The Electronic Serial Number of the device and is a 64-bit integer. |
| iccid | string | The 20-digit Integrated Circuit Card ID (SIM card ID). |
| imei | integer | The 15-digit International Mobile Equipment Identifier. |
| imsi | integer | The International Mobile Subscriber Identifier and is a 64-bit integer. |
| mac | string | The Media Access Control address of the device, listed on the device in the format XX-XX-XX-XX-XX-XX or XX:XX:XX:XX:XX:XX. |
| manufacturer | string | The name of the manufacturer of the device. |
| meid | string | The 56-bit Mobile Equipment ID. |
| msisdn | string | The Mobile Station International Subscriber Directory Number. In the USA, this is 1+ a 10-digit phone number. |
| node_uuid | string | The UUID of the node the device is associated with. A UUID is a 34 or 36-bit alphanumeric value. |
| qrcode | string | The numeric value of the Quick Response (QR) code on the device. |
| serial | string | The device's serial number. |
Specific to the tilt sensor:
| Parameter | Data Type | Description |
|---|---|---|
| mode | string | The reporting mode of the sensor. This can be periodic (report only at intervals) or reportOnChange (report when a change is detected). |
| periodic-reporting | object | a object defining the intervals (in hours or minutes) that the sensor reports data. This value is valid regardless of the sensor's mode. |
| holdTime | integer | The amount of time, in milliseconds, that a change condition must exist for the sensor to report it. |
| angle-away | integer | The threshold defined, in degrees, to send an alert when the sensor has moved away from vertical. |
| angle-toward | integer | The threshold defined, in degrees, to send an alert when the sensor has moved towards vertical. |
| tscore | object | the object containing the profile ID information |
| profileid | string | The UUID of the profile. A UUID is a 34 or 36-bit alphanumeric value. |
| profileversionid | string | The UUID of the profile's version. A UUID is a 34 or 36-bit alphanumeric value. |
Request Body
Example Request for Bluetooth Low Energy (BLE):
{
"accountname": "0000123456-00001",
"configuration": {
"deviceConfig": {
"ble": {
"dataMode": 1,
"manufacturerId": 13200,
"maxNumScan": 100,
"minSigStr": -115,
"monitorPeriod": 300,
"moreManufId": [
{}
],
"opMode": 1,
"reportOffset": 0,
"reportPeriod": 300,
"reportType": 2,
"scanDuration": 20
}
}
},
"resourceidentifier": {
"deveui": "The unique EUI64 address of the device",
"deviceid": "The UUID of the device",
"esn": 223372036854775800,
"iccid": "The 20-digit Integrated Circuit Card ID (SIM card ID)",
"imei": 223372036854775,
"imsi": 223372036854775800,
"mac": "The Media Access Control address of the device, listed on the device in the format XX-XX-XX-XX-XX-XX or XX:XX:XX:XX:XX:XX",
"manufacturer": "REOLINK",
"meid": "The 56-bit Mobile Equipment ID",
"msisdn": "The Mobile Station International Subscriber Directory Number. In the USA, this is 1+ a 10-digit phone number",
"node_uuid": "The UUID of the node the device is associated with",
"qrcode": "The Quick Response (QR) code",
"serial": "The device's serial number"
}
}Example request for the RBS high precision tilt sensor:
{
"accountName": "0000123456-00001",
"configuration": {
"RbsHighPrecisionTiltConfig": {
"mode": "reportOnChange",
"periodic-reporting": {
"unit": "minutes",
"hours": 0,
"minutes": 12
},
"hold-time": 5000,
"angle-away": 5,
"angle-toward": 5,
"tscore": {
"profileid": "the UUID of the profile",
"profileversionid": "the UUID of the profile version"
}
}
},
"resourceidentifier": {
"id": "the UUID of the resource"
}
}Success Response
Status 200
This is a synchronous response, so the configuration details of the device will be returned.
Example Response:
{
"actionresult": [
{
"createdon": "2023-10-02T15:46:34.562Z",
"description": "Failed to forward the event to the provider.",
"deviceid": "The UUID of the device",
"errmsg": "provider_service_error",
"fields": {
"deviceConfig": {
"ble": {
"dataMode": 1,
"manufacturerId": 13200,
"maxNumScan": 100,
"minSigStr": -115,
"monitorPeriod": 300,
"moreManufId": [
{}
],
"opMode": 1,
"reportOffset": 0,
"reportPeriod": 300,
"reportType": 2,
"scanDuration": 20
}
}
},
"foreignid": "c1f178d3-eeee-ffff-gggg-0d6b7ae6022a",
"id": "string",
"lastupdated": "2023-10-02T15:46:34.562Z",
"state": "success",
"transactionid": "afbcc00d-eeee-ffff-gggg-38b4333fcf06",
"version": "1.0",
"versionid": "337bd2e8-eeee-ffff-gggg-5207992fd395"
}
]
}Success Parameters
| Parameter | Data Type | Description |
|---|---|---|
| actionresult | array | Contains all of the detail objects in the response. |
| createdon | string ($date-time) | The timestamp of when the record was created. |
| description | string | A brief description of the request. |
| deviceid | string | The UUID of the device. This value is assigned when the device is onboarded. A UUID is a 32 to 36-bit alphanumeric string. |
| errmsg | string | A system generated error message. |
| fields | object | Contains the device configuration details as well as device identifier details. |
| deviceConfig | object | Configuration details specific to the technology of the sensor. These examples are Bluetooth Low Energy (BLE) and RBS high precision tilt sensor. |
| dataMode | integer | The format of the data output. This varies by device and manufacturer. |
| manufacturerId | integer | A numeric ID of the manufacturer. |
| maxNumScan | integer | How frequently to scan the device. This varies by device and manufacturer. |
| minSigStr | integer | The minimum signal strength required to transmit (in Decibels or dB) |
| monitorPeriod | integer | The period of time to monitor the device. This varies by device and manufacturer. |
| moreManufId | array | Additional manufacturer information. |
| opMode | integer | Operation mode. This value varies by device and manufacturer. |
| reportOffset | integer | The ammount of time between a sensor reading and data being reported. |
| reportPeriod | integer | When the sensor sends data. |
| reportType | integer | The type of report sent by the device. This varies by device and manufacturer. |
| scanDuration | integer | The ammount of time spent polling a device. This varies by device and manufacturer. |
| foreignid | string | The UUID value of the user's Enterprise Customer Profile Database (ECPD) account. A UUID is a 32 to 36-bit alphanumeric string. |
| id | string | The UUID of the resource record. A UUID is a 32 to 36-bit alphanumeric string. |
| lastupdated | string ($date-time) | The timestamp of when the last update to the record was made. |
| state | string | The status of the request made. This will be success or failed. |
| transactionid | string | The UUID of this transaction. A UUID is a 32 to 36-bit alphanumeric string. |
| version | string | The resource version. |
| versionid | string | The UUID of the resource version. A UUID is a 32 to 36-bit alphanumeric string. |
Failure Responses
Example Response:
{
"error": "Error name or code",
"error_description": "A longer error description.",
"cause": "A cause for the error"
}