GetDeviceConnectionHistory

Returns a list of network connection events for a device during a specified time period.

Best Practices

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.

It is best to request only a few days of history at a time. If a device has a lot of connection events, and a GetDeviceConnectionHistory request covers many days, the request may time out with an "unexpected error" when the response cannot be returned within 30 seconds.

Despite the error message, the request is still processing on the M2M Platform. If your application waits a few seconds and sends the request again, the M2M Platform will recognize the duplicate request and return the response from the first request when it is available (assuming that the continued processing does not exceed another 30 seconds).

Sending more frequent requests that cover shorter spans of time can avoid this scenario, but your application should still be able to recognize the "unexpected error" from a 30-second timeout, and retry the request.

Request Parameters

Parameter Type Description
Device
required
DeviceIdentifier The device for which you want connection history. 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 connection history has been 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.
ConnectionHistory DeviceConnectionEvent List of device connection events, sorted by the OccurredAt timestamp, oldest first.
OccurredAt dateTime The date and time when the connection event occurred.
ConnectionEventAttributes ConnectionEventAttribute The attributes that describe the connection event, as Key and Value pairs. Note that a single DeviceConnectionEvent can have many ConnectionEventAttributes, as shown in the example SOAP response.
Key string The key for an attribute.
Value string The value of an attribute.
ExtendedAttributes ExtendedAttributesObj Any extended attributes for the event, as Key and Value pairs.
Key string The key for an extended attribute.
Value string The value of an extended attribute.
IsComplete boolean Indicates whether all events have been returned. If IsComplete is "false," send another request with Earliest set to the OccurredAt time of the last returned event plus one millisecond. Continue adjusting the Earliest value and sending requests until IsComplete is "true."

Example SOAP Request

<v2:GetDeviceConnectionHistory>
  <v2:Input>
    <nph:Device>
      <nph1:Kind>esn</nph1:Kind>
      <nph1:Identifier>5A858A24</nph1:Identifier>
    </nph:Device>
    <nph:OccurredAtFilter>
      <nph1:Earliest>2017-02-20T00:00:01Z</nph1:Earliest>
      <nph1:Latest>2017-02-01T00:00:01Z</nph1:Latest>
    </nph:OccurredAtFilter>
  </v2:Input>
</v2:GetDeviceConnectionHistory>

Example SOAP Response

<GetDeviceConnectionHistoryResponse 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>meid</b:Kind>
         <b:Identifier>54689785258599</b:Identifier>
      </a:Device>
      <a:ConnectionHistory>
         <a:DeviceConnectionEvent>
            <a:OccurredAt>2017-01-30T19:30:46Z</a:OccurredAt>
            <a:ConnectionEventAttributes>
               <a:ConnectionEventAttribute>
                  <a:Key>BytesUsed</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Event</a:Key>
                  <a:Value>Start</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Mdn</a:Key>
                  <a:Value>1585725313</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Username</a:Key>
                  <a:Value>1585725313@vzw3g.com</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2BeginSession</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2CorrelationId</a:Key>
                  <a:Value>3iB2DIPa</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2OriginatingNumberSdbs</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2ReleaseIndicator</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2TerminatingNumberSdbs</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3GppBsId</a:Key>
                  <a:Value>11dd2aa133</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>InputBytes</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>OutputBytes</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>AccountSessionId</a:Key>
                  <a:Value>JRadius-967b493fa333</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>AccountSessionTime</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>AccountTerminateCause</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>CallingStationId</a:Key>
                  <a:Value>8586667777</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>FramedIpAddress</a:Key>
                  <a:Value>10.222.11.2</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2ActiveTime</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2BadPppFrameCount</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2FchFrameSize</a:Key>
                  <a:Value>2</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2ForwardFchMuxOption</a:Key>
                  <a:Value>2337</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2ForwardFchRc</a:Key>
                  <a:Value>3</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2ForwardTrafficType</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2InboundMobileIpSigBytes</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2IpTechnology</a:Key>
                  <a:Value>2</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2OriginatingSdbByteCount</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2OutboundMobileIpSigBytes</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2ReverseFchMuxOption</a:Key>
                  <a:Value>2337</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2ReverseFchRc</a:Key>
                  <a:Value>3</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2ReverseTrafficType</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2ServiceOption</a:Key>
                  <a:Value>33</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2SessionContinue</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2TerminatingSdbByteCount</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>AccountInputPackets</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>AccountOutputPackets</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>AccountStatusType</a:Key>
                  <a:Value>Start</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>NasIdentifier</a:Key>
                  <a:Value>10.0.0.1</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>NasIpAddress</a:Key>
                  <a:Value>167772161</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>NasPort</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2CompulsoryTunnelIndicator</a:Key>
                  <a:Value>0</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2HomeAgentIpAddress</a:Key>
                  <a:Value>10.0.0.1</a:Value>
               </a:ConnectionEventAttribute>
               <a:ConnectionEventAttribute>
                  <a:Key>Account3Gpp2PcfIpAddress</a:Key>
                  <a:Value>10.0.0.1</a:Value>
               </a:ConnectionEventAttribute>
            </a:ConnectionEventAttributes>
            <a:ExtendedAttributes i:nil="true" xmlns:b="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common"/>
         </a:DeviceConnectionEvent>
      </a:ConnectionHistory> 
      <a:IsComplete>true</a:IsComplete>
   </Output>
</GetDeviceConnectionHistoryResponse>

Request Schema Diagram

Response Schema Diagram