Transfer a line of service to a replacement eUICC device

Uses and Requirements

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:

ChangeDeviceState Deactivation when the original ICCID is deactivated
ChangeDeviceIdentifer when the original MDN is transferred to the newly installed device
GoToState when the new line of service is activated on the swapped-out device

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.

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/devices/actions/eidDeviceSwap

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

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 service plan code to assign to the new line of service for the swapped out device.

Identify the SM-SR system:

Parameter Name	Data Type	Description
smsrOid required	string	The Object ID of the SMSR system.

Example Request Body

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

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": "595f5c44-c31c-4552-8670-020a1545a84d"}

Example Success Callback Response

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

## Transfer a line of service to a replacement eUICC device ### Uses and Requirements 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: - ChangeDeviceState Deactivation when the original ICCID is deactivated - ChangeDeviceIdentifer when the original MDN is transferred to the newly installed device - GoToState when the new line of service is activated on the swapped-out device 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. ### Request Components HTTP Request POST https://thingspace.verizon.com/api/m2m/v1/devices/actions/eidDeviceSwap 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 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 service plan code to assign to the new line of service for the swapped out device. | Identify the SM-SR system: | Parameter Name | Data Type | Description | |:-----------------:|:---------:|:---------------------------------:| | smsrOid required | string | The Object ID of the SMSR system. | ### Example Request Body ```json { "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" } ``` ### 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 ```json { "requestId": "595f5c44-c31c-4552-8670-020a1545a84d" } ``` ### Example Success Callback Response Device deactivated ```json { "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 ```json { "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 ```json { "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" } } } ```

Verizon 5G Edge API Portal

Transfer a line of service to a replacement eUICC device