GetAggregateDeviceUsage

Returns the total amount of data sent and the total number of SMS messages sent or received by devices in a specified timeframe. The information is returned in a callback response, so you must register a URL endpoint to receive DeviceUsage callback messages using the Register Callback API in the Callback Registration Service.

Uses and Requirements

About Data Usage Calculations

The ThingSpace Platform calculates various types of usage data: data usage, SMS usage, and rated usage. For RTR customers, domestic usage and international usage may also be returned. 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.

You can request aggregated usage using a device identifier, or a segment label, which must be established using the SetUsageSegmentationLabels method.

Request Parameters

Parameter Type Description
DeviceList
optional*
DeviceIdentifier A list of one or more devices for which you want usage data.

You cannot use DeviceGroupName if you use DeviceList. You can use GetDeviceList to get a list of all devices in the account.

Kind
required for DeviceList
string The type of the device identifier. Valid types of identifiers are:

  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MDN
  • MEID (hexadecimal)
  • MSISDN
Identifier
required for DeviceList
string The value of the device identifier.
DeviceGroupName
optional*
string The device group for which you want usage data.
AccountName
optional*
string

The AccountName element has two uses:

  • To retrieve the aggregate device usage for all devices associated in the account, specify the AccountName without specifying either DeviceList or DeviceGroupName.
  • To retrieve the aggregate device usage for all devices in a device group, you must specify an AccountName along with a DeviceGroupName.
TimestampFilter
required
TimeRange The time period for which you want usage data, specified as a Start and End dateTime. Start cannot be more than 6 months before the current date, and there cannot be more than one month between Start and End.
Start
required for TimestampFilter
dateTime The beginning of the reporting period. Cannot be more than 6 months before the current date.
End
required for TimestampFilter
dateTime The end of the reporting period. Cannot be more than 1 month from the Start date.
Label LabelIdentifier Label name and value associated with the device.
Name varchar(20) The label name associated with the device. For example, VIN.
Value varchar(50) The label value.

* You can either specify up to 10,000 individual devices with the DeviceList parameter, or you can run the request on all devices in an account or device group.

Response Parameters

Parameter Type Description
RequestId string

A unique string that associates the request with the results that are sent via a callback service.

The callback message will contain the information for all devices that match the request criteria. If there are a large number of results, the response will be split into multiple callbacks. Those will be followed by a final callback message indicating that the request has been completed. All of the callback messages will have the same RequestId.

Callback Response Parameters

Parameter Type Description
CallbackRequest CallbackRequest Wrapper element for all callback elements.
Username string The username defined when a URL was registered for the callback service, or an empty element if no username was defined.
Password string The password defined when a registered for the callback service, or an empty element if no password was defined.
RequestId string A unique string that matches the RequestId returned in the synchronous response to the original API request.

A separate callback message is sent for each device that matched the request criteria, indicating whether the operation succeeded for that device. All of the callback messages will have the same RequestId.

Device DeviceIdentifier The device that was changed.
Kind string The type of the device identifier. Valid types of identifiers are:
  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MDN
  • MEID (hexadecimal)
  • MIN
  • MSISDN
Identifier string The value of the device identifier.
Data CallbackData The data elements for this callback.
CarrierService CarrierServiceCallbackRequest Null for this callback service.
ExternalProvisioningChange ExternalProvisioningChange Null for this callback service.
PromoChange PromoChange Null for this callback service.
Usage DeviceUsage The requested device usage information.
Device DeviceIdentifier One or more identifiers for the device.
Kind string The type of the device identifier. Valid types of identifiers are:
  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MDN
  • MEID (hexadecimal)
  • MIN
  • MSISDN
Identifier string The value of the device identifier.
DataUsage string The sum of all data, in bytes, that the device sent or received during the specified dates.
SMSUsage string The sum of all SMS usage by the device during the specified dates. This number includes all SMS messages sent by the device and all acknowledged messages sent to the device.
MoSms int The number of SMS messages sent by the device during the reporting period.
MtSms int The number of SMS messages sent to the device during the reporting period.
StartDate dateTime string The first date in the reporting period, in dateTime format.
EndDate dateTime string The last date in the reporting period, in dateTime format.
Fault SoapFault Device-level fault code and information.
Label LabelIdentifier Label name and value associated with the device.
Name varchar(20) The label name associated with the device. For example, VIN.
DomesticUsage int Domestic usage in bytes.
InternationalUsage int International usage in bytes.
Value varchar(50) The label value.
SMSDelivery SMSDelivery Null for this callback service.
PRLInformation PRLInformation Null for this callback service.
DeviceSuspendStatus DeviceSuspendStatus Null for this callback service.
Fault SoapFault Information about any errors that may have occurred.
faultcode QName
faultstring string
faultfactor anyURI
detail
Comment string Null for this callback service.
Summary SummaryReport Null for this callback service.
Status string Null for this callback service.
CallbackCount integer The number of times this callback message has been sent.
MaxCallbackThreshold integer The maximum number of times this callback message will be sent if it is not correctly acknowledged.

Example SOAP Request using Device Identifier

    <soapenv:Envelope
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:v2="http://nphase.com/unifiedwebservice/v2"
        xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService"
        xmlns:nph1="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
        <soapenv:Header>
            <token xmlns="http://nphase.com/unifiedwebservice/v2">d0b1e4ee-402c-4fd6-ad1d-47722ddd244d</token>
        </soapenv:Header>
        <soapenv:Body>
            <v2:GetAggregateDeviceUsage>
                <v2:Input>
    				<!--Optional:-->
                    <nph:DeviceList>
                        <nph1:DeviceIdentifier>
                            <nph1:Kind>eid</nph1:Kind>
                            <nph1:Identifier>19740048979615732358200659283985</nph1:Identifier>
                        </nph1:DeviceIdentifier>
                    </nph:DeviceList>
    				<!--Optional:-->
                    <nph:DeviceGroupName xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                    <!--Optional:-->
    				<nph:AccountName>0342330389-00001</nph:AccountName>
                    <nph:TimestampFilter>
                        <nph1:Start>2020-12-01</nph1:Start>
                        <nph1:End>2020-12-31</nph1:End>
                    </nph:TimestampFilter>
    				<!--Optional:-->
    				<nph:Label xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                </v2:Input>
            </v2:GetAggregateDeviceUsage>
        </soapenv:Body>
    </soapenv:Envelope>

Example SOAP Request using Label (VIN)

  <soapenv:Envelope
      xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:v2="http://nphase.com/unifiedwebservice/v2"
      xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService"
      xmlns:nph1="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
      <soapenv:Header>
          <token xmlns="http://nphase.com/unifiedwebservice/v2">d3d6efac-d20c-4744-88c9-e8cd6c6a8211</token>
      </soapenv:Header>
      <soapenv:Body>
          <v2:GetAggregateDeviceUsage>
              <v2:Input>
                  <!--Optional:-->
                  <nph:DeviceList xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                  <!--Optional:-->
                  <nph:DeviceGroupName xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                  <!--Optional:-->
                  <nph:AccountName>0342330389-00001</nph:AccountName>
                  <nph:TimestampFilter>
                      <nph1:Start>2020-12-01</nph1:Start>
                      <nph1:End>2020-12-31</nph1:End>
                  </nph:TimestampFilter>
                  <!--Optional:-->
                  <nph:Label>
                      <nph1:Name>VIN</nph1:Name>
                      <nph1:Value>1234r4367345312123455</nph1:Value>
                  </nph:Label>
              </v2:Input>
          </v2:GetAggregateDeviceUsage>
      </soapenv:Body>
  </soapenv:Envelope>

Example SOAP Response

    <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
        <s:Body>
            <GetAggregateDeviceUsageResponse 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:RequestId>ba75180c-778d-4e66-9b4a-285f65feebb2</a:RequestId>
                </Output>
            </GetAggregateDeviceUsageResponse>
        </s:Body>
    </s:Envelope>

Example SOAP Callback Response

Usage Data Callback Message

    <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    	<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          		xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    		<CallbackRequest xmlns="http://nphase.com/unifiedwebservice/v2">
    			<RequestId>ba75180c-778d-4e66-9b4a-285f65feebb2</RequestId>
    			<Data>
    				<Data>
    					<CarrierService xsi:nil="true"/>
    					<ExternalProvisioningChange xsi:nil="true"/>
    					<PromoChange xsi:nil="true"/>
    					<Usage>
    						<Device>
    							<Kind>EID</Kind>
    							<Identifier>19740048979615732358200659283985</Identifier>
    						</Device>
    						<DataUsage>4096</DataUsage>
    						<SMSUsage>0</SMSUsage>
    						<MoSms>0</MoSms>
    						<MtSms>0</MtSms>
    						<StartDate>2020-12-01T00:00:00.0000000</StartDate>
    						<EndDate>2020-12-31T00:00:00.0000000</EndDate>
    						<Fault xsi:nil="true"/>
    						<Label>
    							<Name>VIN</Name>
    							<Value>1234r4367345312123455</Value>
    						</Label>
    						<DomesticUsage>204800</DomesticUsage>
    						<InternationalUsage>204800</InternationalUsage>
    					</Usage>
    					<SMSDelivery xsi:nil="true"/>
    					<PRLInformation xsi:nil="true"/>
    					<DeviceService xsi:nil="true"/>
    					<GoToState xsi:nil="true"/>
    					<DeviceProfileService xsi:nil="true"/>
    					<AlertService xsi:nil="true"/>
    					<Service xsi:nil="true"/>
    					<DiagnosticsService xsi:nil="true"/>
    					<Fault xsi:nil="true"/>
    					<Comment xsi:nil="true"/>
    					<Summary xsi:nil="true"/>
    					<Status xsi:nil="true"/>
    					<CallbackCount>1</CallbackCount>
    					<MaxCallbackThreshold>4</MaxCallbackThreshold>
    					<ExtendedEnhancedConnectivityService xsi:nil="true"/>
    					<NiddService xsi:nil="true"/>
    				</Data>
    			</Data>
    		</CallbackRequest>
    	</s:Body>
    </s:Envelope>

Request Completed Callback Message

    <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    	<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          		xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    		<CallbackRequest xmlns="http://nphase.com/unifiedwebservice/v2">
    			<RequestId>ba75180c-778d-4e66-9b4a-285f65feebb2</RequestId>
    			<Data>
    				<Data>
    					<CarrierService xsi:nil="true"/>
    					<ExternalProvisioningChange xsi:nil="true"/>
    					<PromoChange xsi:nil="true"/>
    					<SMSDelivery xsi:nil="true"/>
    					<PRLInformation xsi:nil="true"/>
    					<DeviceService xsi:nil="true"/>
    					<GoToState xsi:nil="true"/>
    					<DeviceProfileService xsi:nil="true"/>
    					<AlertService xsi:nil="true"/>
    					<InternalService xsi:nil="true"/>
    					<DiagnosticsService xsi:nil="true"/>
    					<Fault xsi:nil="true"/>
    					<Comment>Request Completed Processing</Comment>
    					<Summary xsi:nil="true"/>
    					<Status xsi:nil="true"/>
    					<CallbackCount>1</CallbackCount>
    					<MaxCallbackThreshold>4</MaxCallbackThreshold>
    					<ExtendedEnhancedConnectivityService xsi:nil="true"/>
    					<NiddService xsi:nil="true"/>
    				</Data>
    			</Data>
    		</CallbackRequest>
    	</s:Body>
    </s:Envelope>

Request Schema Diagram

Response Schema Diagram