GetDeviceSuspensionStatus

Returns service suspension information about one or more devices.

NOTE: This API is currently in limited release, and it must be enabled for your organization before you can use it. You can contact Customer Support or your Verizon Sales Representative to learn about enabling the API for your organization.

Uses and Requirements

You should be familiar with the M2M Service Provisioning Rules before suspending and restoring service for devices.

The returned information includes:

The information is returned in a callback response; calls to this API will return an error if the account doesn't have a registered URL for the DeviceSuspensionStatus callback service.

Request Parameters

Parameter Type Description
DeviceList
optional*
DeviceIdentifier

A list of one or more devices for which you want the suspension status, specified by device identifier. Currently, only devices that are suspended will be included in the response.

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

The name of the account that is associated with the specified device group and/or the specified device. If you have access to multiple billing accounts, you must specify an account name.

An account name is usually numeric, and must include any leading zeros.

DeviceServicePlanFilter
optional*
string The name of a service plan, if you want to only include devices that have that service plan. You can use GetServicePlanList to get a list of all service plans in the account.
DeviceCustomFieldFilter
optional*
CustomFieldFilterObj The names and values of custom fields, if you want to only include devices that have matching custom fields.
Name
required for DeviceCustomFieldFilter
string The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
Value
required for DeviceCustomFieldFilter
string The value of the custom field.

Allowed characters in custom field values:

  • Alphanumeric characters
  • / (forward slash)
  • SPACE
  • @ (at sign)
  • . (period)
  • , (comma)
  • : (colon)
  • - (hyphen)
  • _ (underscore)
  • ( (open parenthesis)
  • ) (close parenthesis)
  • [ (open bracket)
  • ] (close bracket)
  • # (number sign or hash)

* You can either specify up to 10,000 individual devices with the DeviceList parameter, or you can run the request on all devices that have a specified account name, device group name, service plan name, or custom field value. You can specify an AccountName or a DeviceGroupName plus one or both filters to identify only those devices that match all criteria.

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 M2M Platform will send a separate callback message for each device that matched the request criteria, indicating whether the operation succeeded for that device and containing any requested information. 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.

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.
SMSDelivery SMSDelivery Null for this callback service.
PRLInformation PRLInformation Null for this callback service.
DeviceSuspendStatus DeviceSuspendStatus The device's suspend information.
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 15 digits)
  • MDN
  • MEID (hexadecimal)
  • MIN
  • MSISDN
Identifier string The value of the device identifier.
State string The current state of the device.
SuspendDate string The date the device was suspended. "N/A" for devices that are not currently suspended.
ExpectedResumeDate string The date that the device will auto-resume based on the suspend reason code, the account contract, and the number of days that it has already been suspended in the last 12 months. "N/A" for devices that are not currently suspended.
DaysRemainingAutoResume string The number of days before service for the device will automatically resume. "N/A" for devices that are not currently suspended.
MaxSuspendDaysAllowed int The number of suspension days associated with the suspend reason code.
NumDaysSuspendedLast12Months int The number of days that the MDN has been suspended in the past 12 months.
NumDaysSuspendAllowedCurrent12Months int The remaining number of days in the current 12-month period that the MDN is allowed to be suspended.
TimesSuspendedLast12Months int The number of times that the MDN has been suspended in the past 12 months.
Fault SoapFault Any device-specific fault information.
faultcode QName
faultstring string
faultfactor anyURI
detail
GoToState GoToState 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>
    <v2:token>91bd36d3-a063-4600-928b-bb57eeccb9ac</v2:token>
  </soapenv:Header>
  <soapenv:Body>
    <v2:GetDeviceSuspensionStatus>
      <v2:Input>
        <nph:DeviceList>
          <nph1:DeviceIdentifier>
            <nph1:Kind>meid</nph1:Kind>
            <nph1:Identifier>DAD20132013504</nph1:Identifier>
          </nph1:DeviceIdentifier>
        </nph:DeviceList>
      </v2:Input>
    </v2:GetDeviceSuspensionStatus>
  </soapenv:Body>
</soapenv:Envelope>

Example SOAP Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <GetDeviceSuspensionStatusResponse xmlns="http://nphase.com/unifiedwebservice/v2">
      <Output xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:a="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService">
            <a:RequestId>6d5ccc6a-d3bc-4a9c-8466-c7f67c15e1f4</a:RequestId>
      </Output>
    </GetDeviceSuspensionStatusResponse>
  </s:Body>
</s:Envelope>

Example Callback Response

Suspension Status 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">
      <Username/>
      <Password/>
      <RequestId>5ddb1e8a-8539-40fa-b3c5-b2c63281fbe2</RequestId>
      <Data>
        <Data>
          <CarrierService xsi:nil="true"/>
          <ExternalProvisioningChange xsi:nil="true"/>
          <PromoChange xsi:nil="true"/>
          <SMSDelivery xsi:nil="true"/>
          <PRLInformation xsi:nil="true"/>
          <DeviceSuspendStatus>
            <Device>
              <Kind>Mdn</Kind>
              <Identifier>9083074681</Identifier>
            </Device>
            <Device>
              <Kind>Meid</Kind>
              <Identifier>A100001F702731</Identifier>
            </Device>
            <State>suspend</State>
            <SuspendDate>02/29/2017</SuspendDate>
            <ExpectedResumeDate>04/01/2017</ExpectedResumeDate>
            <MaxSuspendDaysAllowed>180</MaxSuspendDaysAllowed>
            <NumDaysSuspendedLast12Months>93</NumDaysSuspendedLast12Months>
            <NumdaysSuspendAllowedCurrent12Months>87</NumdaysSuspendAllowedCurrent12Months>
            <Fault xsi:nil="true"/>
          </DeviceSuspendStatus>
          <GoToState 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 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">
      <Username/>
      <Password/>
      <RequestId>5ddb1e8a-8539-40fa-b3c5-b2c63281fbe2</RequestId>
      <Data>
        <Data>
          <CarrierService xsi:nil="true"/>
          <ExternalProvisioningChange xsi:nil="true"/>
          <PromoChange xsi:nil="true"/>
          <SMSDelivery xsi:nil="true"/>
          <PRLInformation xsi:nil="true"/>
          <GoToState 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/>
        </Data>
      </Data>
    </CallbackRequest>
  </s:Body>
</s:Envelope>

Request Schema Diagram

Response Schema Diagram