Change Device Identifier:

PUT /devices/{serviceType}/actions/deviceId

Changes the identifier of a 3G or 4G device to match hardware changes made for a line of service. Use this request to transfer the line of service and the MDN to new hardware, or to change the MDN.

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.

The ThingSpace Platform sends a CarrierService callback message when the device identifier has been changed, or if there was a problem and the change could not be completed.

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

{
  "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"
}

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

Try It Out!