POST /devices/actions/eidDeviceSwap
Transfers the line of service for a 4G eUICC device to another device to correspond with hardware changes, such as swapping out a device. All current device information is transferred to the new device, including the MDN, service plan, and usage history. ThingSpace creates a new line of service for the replaced (swapped out) device and notifies the SMSR system of the changes.
NOTE: This API method requires eUICC devices that can accept downloadable profiles and your SM-SR must be integrated with the Verizon SM-DP.
See also:
Change Device Identifier
The replacement device (the one being swapped in) can be a new device or one that already has an active line of service. If the device has an active line of service, that line will be deactivated before the line of service from the swapped out device is assigned.
ThingSpace sends three callback message when the changes have been completed:
The first two callbacks are returned by the Carrier Service and the third one by the State Service. You must register to receive both types of callbacks to get all of these messages.
Device usage history stays with the MDN, so it will transfer from the original device to the new device.
The EUICC profile status stays with the ICCID, so the profile status of the original device will not transfer to the new device. You may need to download a profile to the new device.
POST https://thingspace.verizon.com/api/m2m/v1/devices/actions/eidDeviceSwap
None.
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 . |
Specify the device that is being replaced:
Parameter Name | Data Type | Description |
---|---|---|
accountName required |
string | The name of the billing account that the device belongs to. |
deviceToSwapOut required |
array of DeviceId objects | The device that you want to replace, specified by the device’s MDN, EID, IMEI, and ICCID. |
deviceToSwapOut.kind deviceToSwapOut.id required |
strings | The kind and value of an identifier for the device that is being swapped out. |
Specify the replacement device:
Parameter Name | Data Type | Description |
---|---|---|
deviceToSwapIn required |
array of DeviceId objects | The replacement device, specified by the device’s EID and IMEI. If you are installing a device that already has an active line of service, you must also specify the device’s ICCID. |
deviceToSwapIn.kind deviceToSwapIn.id required |
strings | The kind and value of an identifier for the device that is being installed. |
Set service parameters for the new line of service on the swapped out device:
Parameter Name | Data Type | Description |
---|---|---|
carrierIpPoolName optional |
string | The pool from which the device IP addresses will be derived. If you do not include this element, the default pool will be used. |
mdnZipCode required |
string | The Zip code of the location where the swapped out device will primarily be used. |
serviceName required |
string | The name of a customer-defined service to push the swapped out device to. |
stateName required |
string | The name of a customer-defined stage state to push the swapped out device to. |
servicePlan required |
string | The current swapped out device rate plan code, which will be assigned to the swapped in device. |
Identify the SM-SR system:
Parameter Name | Data Type | Description |
---|---|---|
smsrOid required |
string | The Object ID of the SMSR system. |
{
"accountName":"1223334444-01234",
"deviceToSwapOut":[
{
"kind":"mdn",
"id": "8586928930"
},
{
"kind":"eid",
"id": "666456789123456789123456784008"
},
{
"kind":"imei",
"id": "990013907835573"
},
{
"kind":"iccid",
"id": "42590078891480000008"
}
],
"deviceToSwapIn":[
{
{
"kind":"eid",
"id": "678912789123453456784008666456"
},
{
"kind":"imei",
"id": "990013907884259"
},
}
],
"mdnZipCode":"98802",
"serviceName":"WiFi",
"stateName":"WiFi Activate",
"servicePlan":"4G 2GB",
"smsrOid":"1.3.6.1.4.1.31746.1.500.200.101.5"
}
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. |
{
"requestId": "595f5c44-c31c-4552-8670-020a1545a84d"
}
Device deactivated
{
"username":"",
"password":"",
"requestId":"eb3406b0-15fc-4473-8e84-b92cfb67f22d",
"deviceIds":[
{
"id":"990003420535573",
"kind":"imei"
},
{
"id":"89148000000800784259",
"kind":"iccid"
}
],
"deviceResponse":{
"deactivateResponse":{
"deactivated":true
}
},
"status":"Success",
"callbackCount":1,
"maxCallbackThreshold":4
}
Change Device Identifier Callback for the swapped in device
{
"username":"",
"password":"",
"requestId":"ebc3ee16-386c-4531-8da0-e43fc656bf4d",
"deviceIds":[
{
"id":"89148000004346060638",
"kind":"Iccid"
},
{
"id":"358729070031093",
"kind":"Imei"
},
{
"id":"89033023312150000000000263619234",
"kind":"Eid"
}
],
"deviceResponse":{
"changeIdentifierResponse":{
"deviceIds":[
{
"id":"352971090107661",
"kind":"imei"
},
{
"id":"89033023312150000000000256691984",
"kind":"eid"
},
{
"id":"89148000004346060158",
"kind":"iccid"
}
],
"servicePlan":"18337",
"smsrOid":"1.3.6.1.4.1.31746.1.500.200.101.15",
"profileStatus":""
}
},
"status":"Success",
"callbackCount":1,
"maxCallbackThreshold":4
}
Go To State Callback for the new line of service
{
"username":"",
"password":"",
"requestId": "595f5c44-c31c-4552-8670-020a1545a84d",
"deviceIds":[
{
"id":"99412344682328800000",
"kind":"Iccid"
},
{
"id":"990013907835573",
"kind":"Imei"
}
],
"deviceResponse":{
"usageResponse":[],
"goToStateResponse":{
"deviceIds":[
{
"id":"99412344682328800000",
"kind":"Iccid"
},
{
"id":"990013907835573",
"kind":"Imei"
}
],
"serviceName":"WiFi",
"stateName":"WiFi Activate"
}
}
}
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.