Transfer a line of service to a replacement eUICC device:

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

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 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.

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

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!