Download a Local Profile to a Device:

POST /devices/profile/actions/download_enable
POST /devices/profile/actions/download_disable

Downloads an eUICC local profile to a device and enables the profile (download_enable) or leaves it disabled (download_disable) so that it can be enabled later.

NOTE: This API is currently in limited release, and is not yet available to all customer accounts.

Contents

See also:
Working with eUICC Devices
Enable a Device Profile
Disable a Device Profile
Delete a Device Profile

Uses and Requirements

The device must have been activated and have an assigned ICCID before you can download a local profile to it or make profile changes.

ThingSpace sends an asynchronous DeviceProfileService callback message when the profile has been downloaded, or if there was a problem and the download failed.

Request Components

HTTP Request

Use the first endpoint shown here to download a local profile and enable it, or use the second endpoint to download a local profile that can be enabled later.

    POST https://thingspace.verizon.com/api/m2m/v1/devices/profile/actions/download_enable
    POST https://thingspace.verizon.com/api/m2m/v1/devices/profile/actions/download_disable

Resource Path and Query Parameters

The endpoint of the resource path specifies the action that you want to take:

  • download_enable - Download a local profile to the devices and enable the profile.
  • download_disable - Download a local profile to the devices, but do not enable the profile.

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

The request body identifies the device to which you want to download a local profile.

Parameter Name Data Type Description
devices
required
array of deviceIds objects The EID and ICCID of the device that you want to download a local profile to.
kind,
id

required for devices
strings The type and value of the device identifier.
  • EID (required)
  • ICCID (required)
accountName
required
string The name of a billing account.
An account name is usually numeric, and must include any leading zeros.
smsrOid
required
string The Object ID of the SMSR system.

Example Request Body

Request to download a local profile to a device:

    {
      "devices":[  
        {
           "deviceIds":[
              {  
                "kind":"eid",
                "id":"678912789123453456784008666456"
              },
              {  
                "kind":"iccid",
                "id":"78425989148000000840"
              }
            ]
        }
      ],
      "accountName":"1223334444-00001",
      "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.
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.

Example Success Response

    {
      "requestId": "0ecf5171-cdfb-4d49-a6d3-f9347b73913d"
    }

Example Success Callback Response

Note: If any errors are encountered by the eUICC provisioning system (SM-SR, SM-DP), they will be included in the callback as euiccErrorCode and euiccErrorDesc below the profileStatus field. The euiccErrorCode contains the Subject Code and Error Code, separated by a comma, and the euiccErrorDesc provides additional information about the error.

    {
      "username": "",
      "password": "",
      "requestId": "0ecf5171-cdfb-4d49-a6d3-f9347b73913d",
      "deviceIds": [
        {
          "id": "78425989148000000840",
          "kind": "Iccid"
        },
        {
          "id": "678912789123453456784008666456",
          "kind": "Eid"
        }
      ],
      "deviceResponse": {
        "deviceProfileResponse": {
          "deviceIdentifierCollection": [
            {
              "id": "78425989148000000840",
              "kind": "iccid"
            },
            {
              "id": "678912789123453456784008666456",
              "kind": "eid"
            }
          ],
          "ipAddress": "11.11.11.12",
          "state": "Active",
          "servicePlan": "sp4g",
          "deviceCredential": {},
          "smsrOid": "1.3.6.1.4.1.31746.1.500.200.101.5",
          "profileStatus": "DOWNLOAD_ENABLE",
          "euiccStatus":"EXECUTED_SUCCESS",
          "euiccStatusCode":"1.2.365",
          "euiccStatusDesc":"EUICC device profile has been updated",
          "euiccSubAddressUpdateStatus":"EXECUTED_SUCCESS",
          "euiccSubAddressUpdateStatusCode":"1",
          "euiccSubAddressUpdateStatusDesc":"SUCCESS: Address has been updated"
        }
      },
      "callbackCount": 1,
      "maxCallbackThreshold": 4
    }

Example Executed With Warning Callback Response

Note: If the download was successful, but the enabling of the device did not occur, the callback will return a status of “Success” and the euiccStatus will be “EXECUTED_WITHWARNING”.

    {
      "username" : "user",
      "password" : "user",
      "requestId" : "24da8f8a-d110-4a54-86b4-83fb76aab83c",
      "deviceIds" : [ {
        "id" : "666456789014008",
        "kind" : "Imei"
      }, {
        "id" : "666456789123456789123456784008",
        "kind" : "Eid"
      } ],
      "deviceResponse" : {
        "deviceProfileResponse" : {
          "euiccStatus" : "EXECUTED_WITHWARNING",
          "euiccStatusCode" : "8.2.1,3.9",
          "euiccStatusDesc" : "The use case was expired at notification receiving step. The server did not receive eUICC notification."
        }
      },
      "status" : "Success",
      "callbackCount" : 1,
      "maxCallbackThreshold" : 4
    }

Example Executed Success Callback Response

Note: If the download was successful, but the enabling of the device did not occur initially, there will be a callback with euiccStatus will be “EXECUTED_WITHWARNING”. Subsequently, when the device is enabled, there will be a second callback with euiccStatus will be “EXECUTED_SUCCESS”.

    {
      "username" : "user",
      "password" : "user",
      "requestId" : "24da9f9a-d111-4a14-86b4-93fb76aab83c",
      "deviceIds" : [ {
        "id" : "666456789014008",
        "kind" : "Imei"
      }, {
        "id" : "666456789123456789123456784008",
        "kind" : "Eid"
      } ],
      "deviceResponse" : {
        "deviceProfileResponse" : {
          "deviceIdentifierCollection" : [ {
            "id" : "11245059392641753151",
            "kind" : "iccid"
          }, {
            "id" : "66622223212345678912345678107115",
            "kind" : "eid"
          } ],
          "smsrOid" : "12.67.89",
          "profileStatus" : "DOWNLOAD_ENABLE",
          "euiccStatus" : "EXECUTED_SUCCESS",
          "euiccStatusCode" : "1.2.365",
          "euiccStatusDesc" : "EUICC device profile has been updated",
          "euiccSubAddressUpdateStatus" : "EXECUTED_SUCCESS",
          "euiccSubAddressUpdateStatusCode" : "1",
          "euiccSubAddressUpdateStatusDesc" : "SUCCESS: Address has been updated"
        }
      },
      "status" : "Success",
      "callbackCount" : 4,
      "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!