GetDeviceUsageHistory

Returns the network data usage history of a device during a specified time period.

Uses and Requirements

Each response includes a maximum of 500 records. To obtain more records, you can call the API multiple times, adjusting the OccurredAtFilter each time to start where the previous request finished.

About Data Usage Calculations

The M2M Platform calculates three types of usage data: data usage, SMS usage, and rated usage. These usage data types originate from the following sources:

There is no date range limit for the Device Usage Report. However, in accordance with Verizon Data Retention Policy, the records contained in this report are kept for 12 months. Though you may specify any date range, you will not receive results for records that are older than 12 months.

Request Parameters

Parameter Type Description
Device
required
DeviceIdentifier

The device for which you want usage history, specified by device identifier.

NOTE: You can use GetDeviceList to get a list of all devices in the account.

Kind
required
string The type of the device identifier. Valid types of identifiers are:
  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 15 digits)
  • MDN
  • MEID (hexadecimal)
  • MSISDN
Identifier
required
string The value of the device identifier.
OccurredAtFilter
required
InclusiveDateTimeRange

Defines the reporting period to be included in the response.

For the first request, set Earliest and Latest to cover the time period for which you want data. Check the IsComplete value in the response. If it's "true" then you have received all of the events that occurred during that time. If IsComplete is "false," send another request with Earliest set to the CreatedAt time of the last returned event plus one millisecond. Continue adjusting the Earliest value and sending requests until IsComplete is "true."

Earliest
required
dateTime The earliest date and time in the range.
Latest
required
dateTime The latest date and time in the range.

Response Parameters

Parameter Type Description
Device DeviceIdentifier The device for which the usage history was returned.
Kind string The type of the device identifier. Valid types of identifiers are:
  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 15 digits)
  • MDN
  • MEID (hexadecimal)
  • MIN
  • MSISDN
Identifier string The value of the device identifier.
UsageHistory DeviceUsage List of device usage events, sorted by timestamp, oldest first.
Timestamp dateTime The date and time at which the event occurred.
ServicePlan string The service plan in effect when the event occurred.
BytesUsed long The number of bytes that the device sent or received as a result of this device usage event.
SmsUsed int The number of SMS messages that occurred as a result of this device usage event.
Source string The source of the device usage information for the device usage event, either "raw" (provided by the AAA service) or "processed" (provided by the carrier feed).
ExtendedAttributes ExtendedAttributesObj Any extended attributes for the event, as Key and Value pairs.

Key

Value

string

int

MoSms

The number of SMS messages sent by the device during the reporting period.

Key

Value

string

int

MtSms

The number of SMS messages sent to the device during the reporting period.

IsComplete boolean Indicates whether all event records have been returned. A maximum of 500 records are returned per call to this API. If IsComplete is "false," send another request with Earliest set to the last Timestamp in this response plus one millisecond. Continue adjusting the Earliest value and sending requests until IsComplete is "true."

Example SOAP Request

<v2:GetDeviceUsageHistory>
  <v2:Input>
    <nph:Device>
      <nph1:Kind>esn</nph1:Kind>
      <nph1:Identifier>5A858A24</nph1:Identifier>
    </nph:Device>
    <nph:TimestampFilter>
      <nph1:Earliest>2014-03-01T00:00:01Z</nph1:Earliest>
      <nph1:Latest>2014-03-31T00:00:01Z</nph1:Latest>
    </nph:TimestampFilter>
  </v2:Input>
</v2:GetDeviceUsageHistory>

Example SOAP Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <GetDeviceUsageHistoryResponse xmlns="http://nphase.com/unifiedwebservice/v2">
      <Output xmlns:a="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:Device xmlns:b="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
          <b:Kind>esn</b:Kind>
          <b:Identifier>5A858A24</b:Identifier>
        </a:Device>
        <a:UsageHistory>
          <a:DeviceUsage>
            <a:Timestamp>2017-04-06T00:00:00+00:00</a:Timestamp>
            <a:ServicePlan>PLN</a:ServicePlan>
            <a:BytesUsed>888</a:BytesUsed>
            <a:SmsUsed>70</a:SmsUsed>
            <a:Source>Verizon Wireless Usage</a:Source>
            <a:ExtendedAttributes i:nil="true" 
             xmlns:b="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common"/>
              <b:ExtendedAttributesObj>
                <b:Key>MoSms</b:Key>
                <b:Value>62</b:Value>
              </b:ExtendedAttributesObj>
              <b:ExtendedAttributesObj>
                <b:Key>MtSms</b:Key>
                <b:Value>8</b:Value>
              </b:ExtendedAttributesObj>
            </a:ExtendedAttributes>
          </a:DeviceUsage>
          <a:DeviceUsage>
            <a:Timestamp>2017-04-07T00:00:00+00:00</a:Timestamp>
            <a:ServicePlan>PLN1</a:ServicePlan>
            <a:BytesUsed>888</a:BytesUsed>
            <a:SmsUsed>700</a:SmsUsed>
            <a:Source>Verizon Wireless Usage</a:Source>
            <a:ExtendedAttributes i:nil="true" 
             xmlns:b="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common"/>
          </a:DeviceUsage>
        </a:UsageHistory>
        <a:IsComplete>true</a:IsComplete>
      </Output>
    </GetDeviceUsageHistoryResponse>
  </s:Body>
</s:Envelope>

Request Schema Diagram

Response Schema Diagram