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:

The ThingSpace Platform updates data usage estimates in near real time, to within 15 minutes of the end of a device’s last data session. For 4G devices that stay connected for extended periods, usage estimates are updated approximately every 6 hours until the device disconnects.
The Verizon Enterprise Network updates SMS usage data every 24 hours, with SMS usage accumulated as of 48 hours in the past, for a total maximum delay of three days.
A Verizon Data Warehouse feed updates rated data and SMS usage daily, with unbilled, non-roaming usage data that is usually two days in arrears. Roaming data may be updated less frequently.

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.

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>