MoveDevice

Move active devices from one billing account to another within a customer profile.

NOTE: This API method requires special account configuration, and it must be enabled for your organization before you can use it. Contact Customer Support or your Verizon Sales Representative and ask about being put on the IoT Workflow or IoT Order Flow to enable this method.

Uses and Requirements

Device Moves vs. Transfers

A Device Move involves moving a device from one billing account to another billing account (e.g. 0123456789-00001 to 9876543210-00001).
A Device Transfer involves moving a device from one sub-account to another sub-account under the same billing account (e.g. 0123456789-00001 to 0123456789-00002).

Device History

All device history (usage history, connection history, etc.) from before the move is retained under the original billing account. Data usage and connections that occur after the move are tracked under the new account. Device attributes, such as service plan and custom field values, are retained when possible, or new values can be specified.

Usage Notes

Account Requirements

Request Parameters

Parameter Type Description
DeviceList
optional*
DeviceIdentifierCollection A list of the devices that you want to move, specified by device identifier. You only need to provide one identifier per device. Do not pass DeviceGroupNameFilter, AccountNameFilter, DeviceCustomFieldFilter, or DeviceServicePlanFilter if you use this parameter.

NOTE: 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.
DeviceGroupNameFilter
optional*
string The name of a device group, if you want to only include devices in that group.

NOTE: You can use GetDeviceGroupList to get a list of all device groups in the account.

AccountNameFilter
optional*
string

The name of a billing account, which can serve one of two purposes:

  • If you want to move all devices in an account.
  • This parameter is required if you are passing DeviceServicePlanFilter or DeviceCustomFieldFilters.

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

DeviceServicePlanFilter
optional*
string A service plan code, 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*
CustomField The names and values of custom fields, if you only want to change 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)
AccountName
required
string The name of the billing account that you want to move the devices to.
ServicePlan
optional
string The service plan code that you want to assign to the devices in the new account. If you do not include this element, the ThingSpace Platform will attempt to use the current service plan, which will result in a error if the new account does not have that service plan.
CarrierIpPoolName
optional
string The pool from which your device IP addresses will be derived in the new account. If you do not include this element, the default pool will be used.
DeviceGroupName
optional
string

The name of the device group in the new account that the devices should be assigned to. If omitted, the ThingSpace Platform will use the current device group name, which will result in an error if the new account does not have a device group with that name.

The devices are only assigned to the device group if the move is successful.

CustomFields
optional
CustomField The names and values of up to five custom fields that you want to set for the devices in the new account. Any existing custom field values will be kept unless you change them by specifying them here.
Name
required for CustomFields
string The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
Value
required for CustomFields
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 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 URL was 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 moved.
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 Null for MoveDevice requests.
ChangeDeviceFeatureCodes ChangeDevicefeatureCodesResponse Null for MoveDevice requests.
ChangeDeviceServicePlan ChangeDeviceServicePlanResponse Null for MoveDevice requests.
ChangeDeviceCostCenter ChangeDeviceCostCenter Response Null for MoveDevice requests.
ChangeDeviceCustomFields ChangeDeviceCustomFieldsResponse Null for MoveDevice requests.
ChangeDeviceIdentifier ChangeDeviceIdentifierResponse Null for MoveDevice requests.
Change4GDeviceIdentifier Change4GDeviceIdentifierResponse Null for MoveDevice requests.
MoveDevice MoveDeviceResponse Information about the device after it was moved to the new account.
DeviceIdentifier DeviceIdentifierCollection The device identifiers for the device after the move. All known identifiers that are assigned to the device are included in the callback.
Kind string The type of the device identifier. Valid types 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.
IpAddress string The new IP address of the device.
State string The current state of the device.
ServicePlan string The service plan code assigned to the device in the new account.
AccountName string The name of the new account that the device is associated with.
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 for this callback service.
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:MoveDevice>
      <v2:Input>
        <nph:DeviceList>
          <nph1:DeviceIdentifierCollection>
            <nph1:DeviceIdentifiers>
              <nph1:DeviceIdentifier>
                <nph1:Kind>ICCID</nph1:Kind>
                <nph1:Identifier>42598914800000080078</nph1:Identifier>
              </nph1:DeviceIdentifier>
            </nph1:DeviceIdentifiers>
          </nph1:DeviceIdentifierCollection>
        </nph:DeviceList>
        <nph:AccountName>0212345678-00001</AccountName>
      </v2:Input>
    </v2:MoveDevice>
  </soapenv:Body>
</soapenv:Envelope>

Example Successful SOAP Response

<MoveDeviceResponse 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>
</MoveDeviceResponse>

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 xsi:nil="true"/>
            <ChangeDeviceFeatureCodes xsi:nil="true"/>
            <ChangeDeviceServicePlan xsi:nil="true"/>
            <ChangeDeviceCostCenter xsi:nil="true"/>
            <ChangeDeviceCustomFields/>
            <ChangeDeviceIdentifier xsi:nil="true"/>
            <Change4GDeviceIdentifier xsi:nil="true"/>
            <MoveDevice>
              <DeviceIdentifier>
                <Kind>iccid</Kind>
                <Identifier>89148000000800784259</Identifier>
              </DeviceIdentifier>
              <IpAddress>10.224.48.88</IpAddress>
              <State>Active</State>
              <ServicePlan>M2M5GB</ServicePlan>
              <AccountName>0212345678-00001</AccountName>
            </MoveDevice>
            <ChangeDeviceContactInfo xsi:nil="true"/>
          </CarrierService>
          <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 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