Retrieve Device Usage

POST /v1/devices/usage/actions/promodeviceusage

Retrieves device data usage relative to the MDNless promotion period.

 

See also:
Retrieve Aggregate Usage for a Device

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/devices/usage/actions/promodeviceusage

Resource Path and Query Parameters

 

None.

Header Parameters

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

Parameter Name Data Type Description
Authorization
required
string HTTP Authorization bearer token.
VZ-M2M-Token
required
string A valid session token returned by POST /session/login.
Content-Type
required
string Must be application/json.

Request Body

The request body identifies the device to query for usage as well as the time period to check for usage in.

Parameter Name Data Type Description
deviceId
required
array an array of the kind of device identifier and what the value of that identifier is. 
deviceId.kind
string The type of device identifier. This will be the identifier of the SIM card or ICCID (Integrated Circuit Card ID)
deviceId.value string The 20-digit ICCID.

earliest

string (date-time) The starting time of the query period.
latest
string(date-time)

The ending time of the query period.

Example Request

{
   "deviceId":{
      "kind":"iccid",
      "id":"20-digit ICCID"
   },
   "earliest":"2021-08-15T 00:00:00Z",
   "latest":"2021-08-16T 00:00:00Z"
}

Success Response

Status 200

{
   "hasMoreData":false,
   "deviceId":{
      "id":"20-digit ICCID",
      "kind":"iccid"
   },
   "usageHistory":[
      {
         "bytesUsed":3072,
         "servicePlan":"service plan name",
         "smsUsed":0,
         "moSMS":0,
         "mtSMS":0,
         "source":"Raw Usage",
         "eventDateTime":"2021-08-15T00:00:00Z"
      }
   ]
}

Response Body

Parameter Name Data Type Description
hasMoreData boolean

This will indicate of there are more pages or more data to retrieve.

  • True - More data is available
  • False - There is no more data
deviceId
array an array of the kind of device identifier and what the value of that identifier is. 
deviceId.kind
string The type of device identifier. This will be the identifier of the SIM card or ICCID (Integrated Circuit Card ID)
deviceId.value string The 20-digit ICCID.

usageHistory

array Usage details
usageHistory.bytesused integer

The whole number value of data transmitted.

usageHistory.servicePlan string

The service plan name.

usageHistory.smsUsed integer

The number of SMS messages sent or received.

usageHistory.moSMS integer

The number of Mobile Originated SMS messages (messages sent)

usageHistory.mtSMS integer

The number of Mobile Terminated SMS messages (messages received).

usageHistory.source string

Where the data is being retreived from. This will show "Raw Usage" unless configured differently.

usageHistory.eventDateTime string(date-time)

The time stamp of the request.

Failure Responses

Status 400

All error messages are returned in this format:

{
  "errorCode": "error code string",
  "errorMessage": "error message string"
}

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

Try It Out!