Assign a SIM Secure License
Assign SIM Secure for IoT Licenses
POST /devices/licenses/actions/assign
Assigns SIM Secure for IoT licenses to SIMs.
Header Parameters
The request header must set the content-type to JSON, contain a current ThingSpace authorization token and a current VZ-M2M session token. For more details on how to get these tokens, visit Getting Started.
| Parameter Name | Data Type | Description |
|---|---|---|
| Authorization (required) | string | HTTP Authorization bearer token: Authorization: Bearer {token} |
| VZ-M2M-Token (required) | string | A valid session token: VZ-M2M-Token: {M2Mtoken} |
| Content-Type (required) | string | Must be application/json Content-Type: application/json |
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. To learn more about callbacks, please visit About Callback Services.
HTTP Request
POST https://thingspace.verizon.com/api/m2m/v1/devices/license/actions/assign
Request Parameters
| 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. |
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.
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
Example Success Response:
{
"requestId": "c3f3d17c-79ff-4b35-82df-94446785b6e0"
}Success Parameters
| 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. |
Failure Responses
Error messages are returned in this format:
{
"errorCode": "error code string",
"errorMessage": "error message string"
}Callback Response
You receive a callback when you initiate SIM Secure for IoT license assignment to SIMs and receive an asynchronous response.
Example Success Callback 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
}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. |