Schedule a firmware upgrade
POST /upgrades
Schedules a firmware upgrade for devices. The response includes an upgrade ID that will be included in all callback notifications about the status of the upgrade, and that you can use to check the status of the upgrade or cancel it.
Note: A synchronous response with no errors means that the request has been accepted, but does not mean that the upgrade has been scheduled. You will receive an “upgradeScheduled” callback message when the upgrade is actually scheduled, and you can check the status of the upgrade to see when it changes from “RequestPending” to “Queued,” which means that the upgrade has been scheduled.
Uses and Requirements
After you send a request to schedule an upgrade, the upgrade advances through several states:
- RequestPending: The upgrade request has been accepted but is not scheduled yet.
- Queued: The upgrade is scheduled, but has not started.
- InProgress: The upgrade is in progress.
- Finished: The upgrade has finished for all devices in the request.
Additionally, if a “RequestPending” upgrade cannot be scheduled, the status will become “RequestFailed,” and if a “Queued” upgrade does not run when scheduled the status will become “UpgradeFailed.” If you have registered a callback URL, ThingSpace will send callback notification messages each time the status of an upgrade changes.
If your account has only a monthly recurring charge (MRC) subscription for the Software Management Services, you must assign a license to each device that you want to upgrade before you can schedule an upgrade for those devices.
Request Components
HTTP Request
POST https://thingspace.verizon.com/api/fota/v1/upgrades
Resource Path and Query Parameters
None.
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 |
Request Body
The request body identifies the devices that you want to upgrade, the firmware image that you want to apply, and the date that you would like the upgrade to start.
| Parameter Name | Data Type | Description |
|---|---|---|
| accountName (required) | string | The name (number) of the billing account. |
| firmwareName (required) | string | The name of the firmware image, from a GET /firmware response. |
| startDate (required) | date string | The date that you would like the upgrade to begin. |
| endDate (optional) | date string | The date at which you would like the upgrade to end. The campaign status will be refreshed throughout the duration if this parameter is set. Note: ThingSpace queues OMA-DM upgrades in the network indefinitely so the upgrade may actually be successful after the end date. Use the Device List API to check the latest reported firmware on the device if the end date has passed. |
| deviceList (required) | array of IMEI strings | The IMEIs of the devices to upgrade. All of the devices must be of the same make and model, and must be at the same firmware version. |
| autoAssignLicenseFlag (optional) | boolean | Valid values include: True: Any devices included in the device list which does not have a license will automatically assign a FOTA license assuming there are enough FOTA licenses available. False: Only devices included in the device list with a license be campaigned. |
| autoAddDevicesFlag (optional) | boolean | Valid values include: True: Beyond the devices included on the device list, any other device(s) which matches the eligibility criteria (same make, model, current firmware, protocol, billing account) will automatically be added to the campaign list during the life of the campaign. False: Do not automatically add devices to the campaign. Note: This flag can be set to true or false when the autoAssignLicense flag is true and must be set to false when the autoAssignLicense flag is false. |
Example Request
Schedule firmware upgrades for two devices:
curl https://thingspace.verizon.com/api/fota/v1/upgrades -H 'Authorization: Bearer $AUTH_TOKEN' -H 'VZ-M2M-Token: $M2M_TOKEN' -H 'Content-Type: application/json' -d
{
"accountName": "0000123456-00001",
"firmwareName": "FOTA_Verizon_Model-A_01To02_HF",
"startDate": "2018-04-01",
"endDate": "2024-12-15",
"devicelist": [
"990003425730535",
"990000473475989"
],
"autoAssignLicenseFlag": true,
"autoAddDevicesFlag": true
}Success Responses
Status 2xx
A successful request returns information about the scheduled upgrade and an upgrade ID that can be used to check the status of the upgrade or cancel it if needed:
| Parameter Name | Data Type | Description |
|---|---|---|
| id | UUID string | The unique identifier for this upgrade. Save this ID so that you can check on the status of the upgrade. |
| accountName | string | The name (number) of the billing account. |
| firmwareName | string | The name of the firmware image that will be used for the upgrade. |
| firmwareTo | string | The name of the firmware version that will be on the devices after a successful upgrade. |
| startDate | string | The intended start date for the upgrade. |
| status | string | The current status of the upgrade, which will always be “RequestPending” for new upgrade requests. |
| deviceList | array of objects | A JSON object for each device that will be upgraded, showing the device IMEI and “RequestPending” status. |
| autoAssignLicenseFlag | boolean | Valid values include: True and False: |
| autoAddDevicesFlag | boolean | Valid values include: True: and False: |
Example Response
"id": "ca0d8809-gggg-eeee-ffff-263559b34bbd",
"accountName": "0000123456-00001",
"firmwareName": "HOSTEDTOSS_Inseego_FW2010e-1_1732737991670",
"make": "Inseego",
"model": "FW2010e-1",
"firmwareTo": "SDX55MOR-4.07.2.1-4.14-4.039",
"startDate": "2024-12-13",
"upgradeStartTime": "2024-12-16T22:10:02Z",
"status": "Finished",
"deviceList": [
{
"deviceId": "900000000000009",
"status": "UpgradeFailed",
"resultReason": "Firmware update to device failed"
}
],
"endDate": "2024-12-15",
"autoAssignLicenseFlag": true,
"autoAddDevicesFlag": trueFailure 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.