Move Devices to Another Account:

`PUT /devices/actions/move`

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.

Move Devices to Another Account:
PUT /devices/actions/move

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

You can only move devices that are in the active state.
The suspension history for moved devices is reset to zero days suspended.
Use separate requests to move 3G and 4G devices unless your accounts are set up to allow both types of devices in the same service plan.
Only move devices from one account at a time. If the request includes devices from more than one account, the devices from one account will be moved and the devices from other accounts will fail.
Both accounts that are "move from/move to" must be under the same ECPD
You must have account access to both the "move to" account and the "move from" account

Account Requirements

The customer profile must be enabled for IoT Order flow.
Devices cannot be moved between subaccounts under a single billing account.
The billing accounts cannot have customer-defined stage states.

ThingSpace sends an asynchronous CarrierService callback message for each device in the request when the device has been moved, or if there was a problem and the move failed.

Request Components

HTTP Request

PUT https://thingspace.verizon.com/api/m2m/v1/devices/actions/move

Resource Path and Query Parameters

None.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.

Parameter Name	Data Type	Description
Authorization required	string	HTTP Authorization bearer token.
VZ-M2M-Token required	string	A valid session token returned by POST /session/login.
Content-Type required	string	Must be `application/json`.

Request Body

The request body identifies the devices that you want to move to another account. You can either specify individual devices in the devices parameter, or you can use the filter parameters to work with devices that match the filter parameter values.

Parameter Name	Data Type	Description
devices optional	array of deviceIds objects	Up to 10,000 devices that you want to move to a different account, specified by device identifier. NOTES Do not include this parameter if you want to use the `filter` parameter to select devices by metadata values.
kind, id required for devices	string	The type and value of the device identifier. ESN - decimal, 11 digits ICCID - decimal, up to 20 digits IMEI - decimal, up to 16 digits MDN - decimal, 10 digits MEID - hexadecimal, 14 characters MSISDN - decimal, 11 digits
filter optional	list of filter parameters	Parameter names and values that you want to use to select the devices to move, instead of specifyng individual devices. If you specify multiple parameters, they will be ANDed together so that only devices that match all of them will be changed.
account	string	The name of a billing account if you have access to multiple accounts and want to include devices in only one account. (An account name is usually numeric, and must include any leading zeros.)
groupName	string	The name of a device group, to only include devices in that group.
servicePlan	string	The name of a service plan, to only include devices with that service plan.
customFields	list of customfield objects	Custom field names and values, if you want to only include devices that have matching values.
key required for customFields filter	string	The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
value required for customFields filter	string	The value of the custom field.
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, ThingSpace will attempt to use the current service plan, which will result in a error if the new account does not have that service plan.
groupName optional	string	The name of the device group in the new account that the devices should be assigned to. If omitted, ThingSpace 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	list of customField objects	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.
key 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.
carrierIpPoolName optional	string	The pool from which device IP addresses will be derived in the new account. If you do not include this element, the default pool will be used.

Example Request Body

Move a single device

{
  "devices":[
    {
      "deviceIds":[
        {
          "kind":"ESN",
          "id":"19110173057"
        }
      ]
    }
  ],
  "accountName":"0212345678-00001",
  "servicePlan":"M2M5GB"
}

Move all devices that are in a specified device group and that have a specified custom field value

{
  "filter":{  
    "groupName":"Short-Haul Trucks",
    "customFields":[  
      {  
        "key":"CustomField1",
        "value":"East Region Trucks"
      }
    ]
  },
  "accountName":"0212345678-00001",
  "servicePlan":"M2M5GB"
}

Success Responses

Status 200

Parameter Name	Data Type	Description
requestId	string	A unique string that associates the request with the results that are sent via a callback service.

Example Success Response

{
  "requestId": "ec682a8b-e288-4806-934d-24e7a59ed889"
}

Example Success Callback Response

{
  "username":"",
  "password":"",
  "requestId":"ec682a8b-e288-4806-934d-24e7a59ed889",
  "deviceIds":[
    {
      "id":"19110173057",
      "kind":"Esn"
    }
  ],
  "deviceResponse":{
    "usageResponse":[ ],
    "moveDeviceResponse":{
      "deviceIds":[
        {
          "id":"19110173057",
          "kind":"Esn"
        }
      ],
      "accountName":"0212345678-00001"
    }
  },
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

Failure Responses

Status 400

All error messages are returned in this format:

{
  "errorCode": "error code string",
  "errorMessage": "error message string"
}

Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.

Try It Out!