GetRatedDeviceUsage

Returns an estimate of billable data and SMS usage for each specified device during their current bill cycle. The information is returned in a callback response, so you must register a URL for the DeviceUsage callback service using the Register Callback API in the Callback Registration Service.

NOTE: The mediated data returned by the GetAggregateDeviceUsage and GetDeviceUsageHistory APIs is more in line with invoices than the data returned by the GetRatedDeviceUsage API. Use of this API is no longer recommended, and it will be deprecated and return an error message in an upcoming release.

Uses and Requirements

Rated usage calculations are conditioned; the ThingSpace Platform subtracts overhead, and also adjusts for attributes such as service plans, day and time, amount of usage, and communication endpoints to help estimate billing amounts. Your actual billing amounts may differ from the estimates returned by this API.

This API does not provide historical information. The callback response includes sums of rated usage from the start of a device’s current bill cycle to the latest date where usage data is available, typically 48 hours before the report is run. Each time a new bill cycle begins, the system reverts rated usage to zero.

IMPORTANT:

The GetRatedDeviceUsage API currently has the following limitation:

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 15 digits)
  • MDN
  • MEID (hexadecimal)
  • MSISDN
Identifier
required for DeviceList
string The value of the device identifier.
DeviceGroupName
optional*
string The name of a device group, if you want to only include devices in that group. You can use GetDeviceGroupList to get a list of all device groups in the account.
AccountName
optional*
string You must specify an AccountName if you specified DeviceGroupName. To retrieve the aggregate device usage for all devices associated with the account, specify the AccountName without specifying either DeviceList or DeviceGroupName.

* 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.

Callback Parameters

NOTE: A single callback can contain information for up to 2000 devices. For requests that contain more than 2000 devices, the ThingSpace Platform will send multiple callbacks, each containing data for up to 2000 devices, until all data is sent. The Platform will send a final callback with the message “Request Completed Successfully” after the last callback containing data. All callbacks will have the same RequestId.

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.
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 DeviceUsage
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 15 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.
StartDate dateTime The first date in the reporting period, in dateTime format.
EndDate dateTime The last date in the reporting period, in dateTime format.
Fault SoapFault Any device-specific fault information.
faultcode QName
faultstring string
faultfactor anyURI
detail
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

<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/>
  <soapenv:Body>
    <v2:GetRatedDeviceUsage>
      <v2:Input>
        <nph:DeviceList>
          <nph1:DeviceIdentifier>
            <nph1:Kind>esn</nph1:Kind>
            <nph1:Identifier>09123456123</nph1:Identifier>
          </nph1:DeviceIdentifier>
        </nph:DeviceList>
      </v2:Input>
    </v2:GetRatedDeviceUsage>
  </soapenv:Body>
</soapenv:Envelope>

Example SOAP Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <GetRatedDeviceUsageResponse xmlns="http://nphase.com/unifiedwebservice/v2">
      <Output xmlns:a="http://schemas.datacontract.org/2004/07NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService"
        xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:RequestId>1886fbbf-22b8-47e3-8fb6-97920e505c28</a:RequestId>
      </Output>
    </GetRatedDeviceUsageResponse>
  </s:Body>
</s:Envelope>

Example Callback Response

<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">
      <Username/>
      <Password/>
      <RequestId>24da9f9a-d110-4a54-86b4-93fb76aab83c</RequestId>
      <Data>
        <Data>
          <CarrierService xsi:nil="true"/>
          <ExternalProvisioningChange xsi:nil="true"/>
          <PromoChange xsi:nil="true"/>
          <Usage>
            <Device>
              <Kind>Mdn</Kind>
              <Identifier>9083074681</Identifier>
            </Device>
            <Device>
              <Kind>Meid</Kind>
              <Identifier>A100001F702731</Identifier>
            </Device>
            <DataUsage>0</DataUsage>
            <SMSUsage>0</SMSUsage>
            <StartDate>2014-02-02T00:00:00.0000000</StartDate>
            <EndDate>2014-02-25T00:00:00.0000000</EndDate>
            <Fault xsi:nil="true"/>
          </Usage>
          <SMSDelivery xsi:nil="true"/>
          <PRLInformation xsi:nil="true"/>
          <DeviceSuspendStatus 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/>
        </Data>
      </Data>
    </CallbackRequest>
  </s:Body>
</s:Envelope>

Request Schema Diagram

Response Schema Diagram