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 ThingSpace Platform. If your application waits a few seconds and sends the request again, the ThingSpace 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 16 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 16 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>