Assign SIM-Secure for IoT Licenses  

POST /devices/licenses/actions/assign

Assigns SIM-Secure for IoT licenses to SIMs.

Contents

Uses and Requirements

You can assign SIM-Secure for IoT licenses to SIMs. Flexible licenses are purchased either a-la-carte or part of a bundle and are designated as: SIMSec-IoT and TS-BUNDLE-KTO-SIMSEC-MRC, respectively. Lifetime licenses are assigned to a SIM for the life of the SIM, and cannot be removed. Lifetime licenses are designated as SIMSec-IoT-Lt. TSS-IOT-INTLG-TIERED-SIMSEC is the SKU for the SIM-Secure flexible license included in the intelligence bundle.

To have a SIM-Secure for IoT license, assigned devices must be:

  • In an active state.
  • Onboarded into ThingSpace/ThingSpace Connectivity Management.
  • Visible within the ThingSpace Manage web portal.
  • Part of the account making the assignment request.
  • 4G devices. Only 4G devices are eligible for SIM-Secure for IoT license assignment.

Note: The user should register for the CarrierService Callback in order to receive callbacks for confirmation or failure of a license assignment. For more information about callbacks, please see About Callback Services and how to Register a Callback Listener.

Request Components

HTTP Request

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

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

The request body identifies the account name, SKU number, and a list of devices to which you want to assign a SIM-Secure for IoT license.

NOTE: You can only assign one license type, or SKU number, per request. To assign different license types, you must use a separate request for each type.

Parameter Name Data Type Description
accountName
required
string The name of a billing account.
This parameter is required only if the UWS account used for the current API session has access to multiple accounts. An account name is usually numeric, and must include any leading zeros.
skuNumber
required
string (20 characters max string) The Stock Keeping Unit (SKU). Valid skuNumbers for license types:
“SIMSec-IoT-Lt”. (Lifetime) Once a license is assigned to a SIM, the SIM-Secure feature is enabled for the life of the SIM.
“TS-BUNDLE-KTO-SIMSEC-MRC”. (Bundle) The SIM-Secure Flex license can be assigned to or removed from a SIM at any time. This SKU is bundled with other ThingSpace Services.
“SIMSec-IoT”. (Flex) The SIM-Secure Flex license can be assigned to or removed from a SIM at any time. This SKU is purchased a la carte. "TSS-IOT-INTLG-TIERED-SIMSEC". (Intelligent Bundle) The SIM-Secure flexible license included in the intelligence bundle.
NOTE: You can only assign one skuNumber in the request body.
devices
required
array of deviceIds objects A list of 4G devices.
kind,
id

required
strings For 4G devices, IMEI (decimal, up to 15 digits) and ICCID (decimal, up to 20 digits), in that order.

Example Request Body

{
  "accountName": "0000123456-00001",
  "skuNumber": "SIMSec-IoT-Lt",
   "devices": [
    {
      "deviceIds": [
        {
          "id": "15-digit IMEI",
          "kind": "imei"
        },
        {
          "id": "20-digit ICCID",
          "kind": "iccid"
        }
      ]
    },
    {
      "deviceIds": [
        {
          "id": "15-digit IMEI",
          "kind": "imei"
        },
        {
          "id": "20-digit ICCID",
          "kind": "iccid"
        }
      ]
    }
  ]
}

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 message.
The ThingSpace Platform sends a separate callback message for each device that matches the request criteria, indicating whether the operation succeeded for that device and containing any requested information. All callback messages will have the same requestId.

Example Success Response

{"requestId": "c3f3d17c-79ff-4b35-82df-94446785b6e0"}

Example Success Callback Response

You receive a callback when you initiate SIM-Secure for IoT license assignment to SIMs and receive an asynchronous response.

{
   "requestId":"c3f3d17c-79ff-4b35-82df-94446785b6e0",
   "deviceIds":[
      {
         "id":"20-digit ICCID",
         "kind":"ICCID"
      },
      {
         "id":"10-digit MDN",
         "kind":"MDN"
      },
      {
         "id":"15-digit IMEI",
         "kind":"IMEI"
      }
   ],
   "deviceResponse":{
      "deviceSkuSubscriptionResponse":{
         "accountName":"0000123456-00001",
         "skuNumber":"TSS-IOT-INTLG-TIERED-SIMSEC",
         "action":"Assign"
      }
   },
   "comment":"",
   "status":"Success",
   "callbackCount":1,
   "maxCallbackThreshold":4
}

Failure Responses

Error messages are returned in this format:

{
  "errorCode": "error code string",
  "errorMessage": "error message string"
}

Error Codes and Messages

Error Code Error Message Description
REQUEST_FAILED.CarrierRequestUnsuccessful REQUEST FAILED: Device already has license assigned. You attempted to assign a license to a device that already has a license assigned.
UnifiedWebService.REQUEST_FAILED.CarrierRequestUnsuccessful REQUEST_FAILED: At least one device exists with Assigned or Pending Assignment or Pending UnAssignment license status. You attempted to assign a license to a device that has already had a license assigned.
Carrier.Service.INPUT_INVALID.SKUNumber.NotDefined skuNumber is a required field. Your request did not include the skuNumber.
Carrier.Service.INPUT_INVALID.Action.NotDefined Action is required. Your request did not include an action.
UnifiedWebService.REQUEST_FAILED.CarrierRequestUnsuccessful REQUEST_FAILED: Devices not found for the specified IMEI and ICCID. Verify the IMEI and ICCID for the device.
Carrier.Service.INPUT_INVALID.DeviceGroupName.NotSupported The Device Group Name is not supported. The device group in the request does not exist.
Carrier.Service.INPUT_INVALID.Action.Invalid The action was not recognized as valid. Verify that your POST request has an “assign” action to assign the license.
UnifiedWebService.INPUT_INVALID.DeviceNotDefined A device must be defined. Your request did not include device information.
CarrierService.INPUT_INVALID.DeviceIdentifierCollection.Null A device identifier collection may not be null. Your request did not specify device identifiers.
UnifiedWebService.INPUT_INVALID.Unassign.NotSupported The unassign action is not supported for SIM-Secure lifetime. You cannot unassign a lifetime license for SIM-Secure.
INPUT_INVALID.InsufficientLicense.Invalid You do not have required licenses to perform this action. The number of devices in your request exceeds the number of available licenses.