Move Devices

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.

Contents

Uses and Requirements

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.

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 15 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
required
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!