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:

• The API is unable to include results from the end of the previous billing cycle. When a Rated Usage Report is run in the first six days of a billing cycle, the results incorrectly show that the devices have used no billable data.
• Actual billing amounts may differ from the estimates in the callback response.
• Usage data is typically two days in arrears for non-roaming data. For example, to obtain data for the first half of a bill cycle, wait until about Day 17 to send the request. Roaming data may be updated less frequently.
• The billing periods in the ThingSpace Platform and the Verizon invoice are off by approximately 6 hours. Usage accumulated in the final 6 hours of the M2M billing cycle appears on the following Verizon bill.

Request Parameters

* 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

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.

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