API Reference
Retrieve Aggregate Usage
POST /devices/usage/actions/list/aggregate
This endpoint retrieves an aggregate, or summary, of usage for the device specified.
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 bearer token: Authorization: Bearer {token} |
| VZ-M2M-Token (required) | string | A valid session token: VZ-M2M-Token: {M2Mtoken} |
| Content-Type (required) | string | Must be application/json Content-Type: application/json |
HTTP Request
POST https://thingspace.verizon.com/api/m2m/v1/devices/usage/actions/list/aggregate
Request Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
| deviceIds (required) | array | The device ID value. |
| id | string | The numeric value of the device ID type. |
| kind | string | The type of device ID represented by the ID value. Only the following are supported by the request and both values must be present: eid - Electronic ID, a 32-digit unique ID of the device NOTE: for this query, only EID is valid. |
| accountName (required) | string | The numeric name of the account. This is in the format 0000123456-00001. Leading zeros must be included. |
| startTime (required) | string ($datetime) | The start of the time period requested. |
| endTime (required) | string ($datetime) | The end of the time period requested. |
Request Body
Example request:
{
"deviceIds": [
{
"id": "32-digit EID",
"kind": "eid"
}
],
"accountName": "0000123456-00001",
"startTime": "2023-10-01T00:00:00Z",
"endTime": "2023-10-30T00:00:00Z"
}Success Response
Status 200 A successful response shows a system generated request ID to track the request.
Example Response:
{
"requestId": "d1f08526-5443-4054-9a29-4456490ea9f8"
}Callback Response
These endpoints send responses asynchronously. In order to read the results a callback is required. To learn more about callbacks, please visit About Callback Services.
Example callback responses:
{
"requestId": "d1f08526-5443-4054-9a29-4456490ea9f8",
"deviceResponse": {
"usageResponse": [
{
"deviceIds": [
{
"id": "32-digit EID",
"kind": "eid"
}
],
"dataUsage": "245971989",
"smsUsage": "6",
"startDate": "2023-10-01T00:00:00.0000000+00:00",
"endDate": "2023-10-30T00:00:00.0000000+00:00",
"moSms": "5",
"mtSms": "1"
}
]
},
"callbackCount": 1,
"maxCallbackThreshold": 4
}Callback Parameters
| Parameter | Data Type | Description |
|---|---|---|
| requestId | string | The requestId being viewed. This is a system generated value from the request above. |
| deviceResponse | object | Contains the response from the device queried. |
| usageResponse | array | The record of usage from the device queried. |
| deviceIds | array | An array of devices being queried by the request. Each deviceId will contain: id, kind |
| id | string | The numeric value of the device ID. |
| kind | string | The type of device ID represented by the ID value: eid - 32-digit Electronic ID |
| dataUsage | string | The total amount of data used (in Bytes) for that time period.. |
| smsUsage | string | The total number of SMS (text) messages sent and received |
| startDate | string ($datetime) | The starting point of the time period queried. |
| endDate | string ($datetime) | The ending point of the time period queried. |
| moSms | string | Mobile Originating SMS. Text messages sent. |
| mtSms | string | Mobile Terminating SMS. Text messages received. |
| callbackCount | string | The number of responses for deviceResponse found. |
| maxCallbackThreshold | string | The maximum number of responses for deviceResponse allowed. |
Failure Responses
All error responses will be in the following format.
{
"errorCode": "The 3-digit HTML error code",
"errorMessage": "string"
}