Retrieve Device Usage

`POST /v1/devices/usage/actions/promodeviceusage`

Retrieves device data usage relative to the MDNless promotion period.

Content

Request Components
Request Example
Success Responses
- Example Success Response
- Failure Responses
Response Body

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!