API Reference

Change Device Identifier

Uses and Requirements

For this 4G Hardware Change	Use this Change4GOption	Notes
Change the SIM in a 4G device	ChangeICCID	The new SIM must be inactive and not already associated with a billing account.
Replace the 4G device and use the current SIM	ChangeIMEI	May require optional ServicePlan parameter to change to a plan that is compatible with the new device.
Replace a 4G device and SIM	ChangeIMEIandICCID	The new SIM must be inactive and not already associated with a billing account. May require optional ServicePlan parameter to change to a plan that is compatible with the new device.
Change the phone number of a 4G device	ChangeMSISDN	You cannot change the hardware (IMEI or ICCID) and the MSISDN in the same API call.
Replace a 3G device with a 4G device	3Gto4G	May require optional ServicePlan parameter to change to a 4G-compatible service plan.
Replace a 4G device with a 3G device	4Gto3G	May require optional ServicePlan parameter to change to a 3G-compatible service plan.
Replace an eUICC device with another one	ChangeIMEIandEID	The request must also include smsrOid. The local profile will have to be downloaded to the new device after this request has finished.

After changing a device identifier, the old identifier cannot be used to get any device history, such as with GetAggrregateDeviceUsage or GetDeviceProvisioningHistory.
You can use a device identifier that did not change to get any type of device history that spans the change date. For example, you can use the MSISDN if you only changed the ICCID.

NOTE: Both of these conditions must be true for this call to succeed:

The existing device must be in the Active state with an MDN/MSISDN assigned.
The new hardware (MEID or ICCID) cannot already be in the ThingSpace Platform database. To reuse a deactivated device, you must first delete the device with a POST /devices/actions/delete request.

REST Request Parameters

HTTP Request

PUT https://thingspace.verizon.com/api/m2m/v1/devices/{serviceType}/actions/deviceId

Resource Path and Query Parameters

You must specify in the resource path whether you are changing 3G or 4G devices.

Parameter Name	Data Type	Description
serviceType required	string	Either “3g” or “4g” depending on the device that's changing. If the device is a 3G device, use "3g". If the device is a 4G device, use "4g". When moving a device from 3G to 4G use "4g".

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

Specify the device to change using the old ID or one that isn’t changing.

Parameter Name	Data Type	Description
deviceIds required	array of DeviceId objects	The device that you want to change, specified by a device identifier. You do not have to use the same kind of device identifier here as the kind that you are changing. For example, if you want to change a device’s ICCID, you can specify the device here by its MSISDN or IMEI, or by its current ICCID.
deviceIds.kind, deviceIds.id required	string	The type and value of the device identifier. EID - decimal, 32 digits 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

Set the new ID and other values.

Parameter Name	Data Type	Description
deviceIdsTo optional	array of DeviceID objects	The new identifier for the device. Required for all change4GOptions except ChangeMSISDN. For 4G devices, the type must match what is required by the selected change4gOption. For 3Gto4G, you must provide both an ICCID and IMEI. For 3G devices, you must specify the new ESN or MEID.
deviceIdsTo.kind, deviceIdsTo.id required	string	The type and value of the device identifier. EID - decimal, 32 digits 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
change4gOption required for 4G	string	The type of change that you want to make for a 4G device. Valid values are: ChangeICCID (put a new SIM in an existing device) ChangeIMEI (put the existing SIM in a new device) ChangeIMEIandICCID (replace both the device and the SIM) ChangeIMEIandEID (replace an eUICC device with a new one) ChangeMSISDN (request a new phone number for the device) 3Gto4G (replace a 3G device with a 4G device) 4Gto3G (replace a 4G device with a 3G device) NOTE: The values are not case sensitive.
zipCode optional	string	The ZIP code from which the MDN and MSISDN will be derived when assignNonGeoMDN is true. Specify the zip code of the location where the line of service will primarily be used.
npaNxx depends on ChangeMSISDN	string	The NPA NXX (area code and prefix) from which the MDN and MSISDN will be derived when assignNonGeoMDN is false. Specify the 6-digit NPA NXX of the location where the line of service will primarily be used. This API checks to see if a number starting with the NPA NXX is available. If not, this API uses the zipCode parameter, if specified, to assign a number in the area of the line of service. This parameter is required when you change an MDN/MSISDN for a B2B carrier, such as Verizon Wireless.
servicePlan optional	string	The code for a different service plan, if you want to change the service plan while changing the device identifier. Set this parameter to one of the Code values returned by GET /plans. Verizon Wireless provides service plan codes at the time of on-boarding and subsequently whenever there are any changes to the service plan. NOTE: Replacing a 3G device with a 4G device, or replacing a 4G device with a 3G device, will most likely require changing the service plan.
assignNonGeoMdn required for ChangeMSISDN	Boolean	Set to true to assign a non-Geo MDN and MSISDN, or false to assign an MDN and MSISDN from a specific NPA-NXX. If this flag is true, zipCode is required (for billing) and npaNxx is optional. If this flag is false, zipCode is optional and npaNxx is required. You cannot change a non-Geo device to have a geographic MDN/MSISDN. NOTE: To use non-geographic MDNs, the account must be configured to support non-Geo MDNs, and the device must be non-Geo capable.
smsrOid required for ChangeIMEIandEID	string	The Object ID of the SMSR system.

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) 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.
ChangeDeviceCustomFields	ChangeDeviceCustomFieldsResponse	Empty in callback messages for ChangeDeviceIdentifier requests. Null for other CarrierService callback messages.
ChangeDeviceIdentifier	ChangeDeviceIdentifierResponse	Contains the new device identifier for successful ChangeDeviceIdentifier requests. Null for other CarrierService callback messages.
DeviceIdentifierChanged	DeviceIdentifier	The new device identifier
Kind	string	The type of the device identifier. Valid types of identifiers are: ESN (decimal) MDN MEID (hexadecimal) MIN MSISDN
Identifier	string	The value of the device identifier.
ServicePlan	string	The name of the new service plan for the device, if the service plan was changed.
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 Success Response:

Status 200

{
  "requestId": "595f5c44-c31c-4552-8670-020a1545a84d"
}

Example Success Callback Response

{  
  "username":"",
  "password":"",
  "requestId":"a28892ea-6503-4aa7-bfa2-4cd45d42f61b",
  "deviceIds":[  
    {  
      "id":"22211315718",
      "kind":"ESN"
    }
  ],
  "deviceResponse":{  
    "changeIdentifierResponse":{  
      "deviceIds":[  
        {  
          "id":"A1000001999990",
          "kind":"iccid"
        }
      ],
      "servicePlan":"M2M_4G"
    }
  },
  "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"
}

Change Device IdentifierCopy Anchor Link

Uses and RequirementsCopy Anchor Link

REST Request ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response ParametersCopy Anchor Link

Example Success Response:Copy Anchor Link