ChangeDeviceState - Deactivate

Deactivates service for one or more devices.

NOTE: Deactivating service for a device may result in an early termination fee (ETF) being charged to the account, depending on the terms of the contract with Verizon. If your contract allows ETF waivers and if you want to use one for a particular deactivation, set the EtfWaiver value to True.

Uses and Requirements

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

You can specify a list of individual devices, or work with all devices in an account or device group. You can limit the devices affected by applying service plan or custom field filters.

The ThingSpace Platform sends an asynchronous CarrierService callback message for each device in the request when service for the device has been deactivated, or if there was a problem and the deactivation failed.

Request Parameters

Parameter Type Description
DeviceList
optional*
DeviceIdentifierCollection

A list of the devices for which you want to deactivate service, specified by device identifier. You only need to provide one identifier per device. Do not pass DeviceGroupName, AccountName, DeviceCustomFieldFilter, or DeviceServicePlanFilter if you use this parameter.

You can use GetDeviceList to get a list of all devices in the account.

For each device in DeviceList, use this structure of nested parameters:

<DeviceIdentifierCollection>
  <DeviceIndentifiers>
    <DeviceIdentifier>
      <Kind></Kind>
      <Identifier></Identifier>
    </DeviceIdentifier>
  </DeviceIndentifiers>
</DeviceIdentifierCollection>
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 16 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 deactivate all devices in that group.
AccountName
optional*
string The name of an account, which can serve one of two purposes:
  • Indicates that you want to change all devices in that account. Do not also pass DeviceList, DeviceGroupName, or any of the filters.
  • This parameter is required if you are passing DeviceGroupName and you have access to multiple accounts, since a device group name can exist in multiple accounts.

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*
CustomFieldFilterObject 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)
Deactivate
required
DeactivateDeviceRequest Deactivates the specified devices.
EffectiveDate
optional
string NOT USED
ReasonCode
required
string A code identifying the reason for the deactivation. Currently the only valid reason code is "FF", which corresponds to General Admin/Maintenance.
EtfWaiver
required
boolean

Fees may be assessed for deactivating Verizon Wireless devices, depending on the account contract. The EtfWaiver parameter waives the Early Termination Fee (ETF), if applicable.

  • When EtfWaiver is set to true, the fee will be waived, assuming that waivers are allowed in the contract and they have not all been used.
  • When EtfWaiver is set to false, the fee will not be waived via this mechanism. If you use a business process where you deactivate devices and apply ETF waivers through some other mechanism, you may continue to follow that process,and simply set EtfWaiver to false.

If your account does not have ETF waivers at all, set EtfWaiver to False. The Deactivate request will fail if you set EtfWaiter to true and there are no waivers available based on the contract.

DeleteAfterDeactivation
optional
boolean Specifies whether you want to delete the device from the database upon deactivation.

* You can either specify 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 ThingSpace 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. 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.

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 16 digits)
  • MDN
  • MEID (hexadecimal)
  • MIN
  • MSISDN
Identifier string The value of the device identifier.
Data CallbackData The data elements for this callback.
CarrierService CarrierServiceCallbackRequest The data returned from a CarrierService API request.
ChangeDeviceState ChangeDeviceStateResponse Contains child elements for successful ChangeDeviceState requests. Null for other CarrierService requests.
Activate ActivateDeviceResponse Null in ChangeDeviceState - Deactivate callback messages.
Deactivate DeactivateDeviceResponse Contains the state and service name of the device, both of which may be null or empty.
StateName string
ServiceName string
Restore RestoreDeviceResponse Null in ChangeDeviceState - Deactivate callback messages.
Suspend SuspendDeviceResponse Null in ChangeDeviceState - Deactivate callback messages.
Reconnect ReconnectDeviceResponse Null in ChangeDeviceState - Deactivate callback messages.
ChangeDeviceFeatureCodes ChangeDevicefeatureCodesResponse Null for ChangeDeviceState requests.
ChangeDeviceServicePlan ChangeDeviceServicePlanResponse Null for ChangeDeviceState requests.
ChangeDeviceCostCenter ChangeDeviceCostCenter Response Null for ChangeDeviceState requests.
ChangeDeviceCustomFields ChangeDeviceCustomFieldsResponse Null for ChangeDeviceState requests.
ChangeDeviceIdentifier ChangeDeviceIdentifierResponse Null for ChangeDeviceState requests.
Change4GDeviceIdentifier Change4GDeviceIdentifierResponse Null for ChangeDeviceState requests.
MoveDevice MoveDeviceResponse Null for ChangeDeviceState requests.
ChangeDeviceContactInfo ChangeDeviceContactInfo Response Null for ChangeDeviceState requests.
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 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 in ChangeDeviceState callback messages.
Summary SummaryReport Null for this callback service.
Status string Success or Failed.
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.CarrierService"
  xmlns:nph1="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common"
  xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
  <soapenv:Header>
    <v2:token>current_session_token</v2:token>
  </soapenv:Header>
  <soapenv:Body>
    <v2:ChangeDeviceState>
      <v2:Input>
        <nph:DeviceList>
          <nph1:DeviceIdentifierCollection>
            <nph1:DeviceIdentifiers>
              <nph1:DeviceIdentifier>
                <nph1:Kind>ESN</nph1:Kind>
                <nph1:Identifier>09611822299</nph1:Identifier>
              </nph1:DeviceIdentifier>
            </nph1:DeviceIdentifiers>
          </nph1:DeviceIdentifierCollection>
        </nph:DeviceList>
        <nph:Deactivate>
          <nph:EffectiveDate></nph:EffectiveDate>
          <nph:ReasonCode>FF</nph:ReasonCode>
          <nph:EtfWaiver>true</nph:EtfWaiver>
          <nph:DeleteAfterDeactivation>true</nph:DeleteAfterDeactivation>
        </nph:Deactivate>
      </v2:Input>
    </v2:ChangeDeviceState>
  </soapenv:Body>
</soapenv:Envelope>

Example SOAP Response

<ChangeDeviceStateResponse xmlns="http://nphase.com/unifiedwebservice/v2">
  <Output xmlns:a="http://schemas.datacontract.org/2004/07NPhase.UnifiedWebService.APIs.v2.Contract.CarrierService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <a:RequestId>2c90bd28-ece4-42ef-9f02-7e3bd4fbff33</a:RequestId>
  </Output>
</ChangeDeviceStateResponse>

Example SOAP Callback

<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>2c90bd28-ece4-42ef-9f02-7e3bd4fbff33</RequestId>
      <Device>
        <Kind>imei</Kind>
        <Identifier>990003420535573</Identifier>
      </Device>
      <Device>
        <Kind>iccid</Kind>
        <Identifier>89148000000800784259</Identifier>
      </Device>
      <Data>
        <Data>
          <CarrierService>
            <ChangeDeviceState>
              <Activate xsi:nil="true"/>
              <Deactivate>
                <StateName xsi:nil="true"/>
                <ServiceName/>
              </Deactivate>
              <Restore xsi:nil="true"/>
              <Suspend xsi:nil="true"/>
              <Reconnect xsi:nil="true"/>
            </ChangeDeviceState>
            <ChangeDeviceFeatureCodes xsi:nil="true"/>
            <ChangeDeviceServicePlan xsi:nil="true"/>
            <ChangeDeviceCostCenter xsi:nil="true"/>
            <ChangeDeviceCustomFields xsi:nil="true"/>
            <ChangeDeviceIdentifier xsi:nil="true"/>
            <Change4GDeviceIdentifier xsi:nil="true"/>
            <MoveDevice xsi:nil="true"/>
            <ChangeDeviceContactInfo xsi:nil="true"/>
          </CarrierService>
          <ExternalProvisioningChange xsi:nil="true"/>
          <PromoChange xsi:nil="true"/>
          <Usage xsi:nil="true"/>
          <SMSDelivery xsi:nil="true"/>
          <PRLInformation xsi:nil="true"/>
          <DeviceSuspendStatus xsi:nil="true"/>
          <GoToState xsi:nil="true"/>
          <Fault xsi:nil="true"/>
          <Comment xsi:nil="true"/>
          <Summary xsi:nil="true"/>
          <Status>Success</Status> 
          <CallbackCount>1</CallbackCount>
          <MaxCallbackThreshold>4</MaxCallbackThreshold/>
        </Data>
      </Data>
    </CallbackRequest>
  </s:Body>
</s:Envelope>

Request Schema Diagram

Response Schema Diagram