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.


See also:
Get information about an upgrade
Get upgrades by status
Modify a scheduled upgrade
Get a list of firmware for an account
Cancel a scheduled upgrade

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


Resource Path and Query Parameters


Header Parameters

The request header must contain a current ThingSpace authorization token and a current VZ-M2M session token, and must set the Content-Type to JSON.

Parameter Name Data Type Description
string HTTP Authorization request header containing a valid Bearer token.
string A valid session token returned by a Connectivity Management POST /session/login request.
string Must be 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
string The name (number) of the billing account.
string The name of the firmware image, from a GET /firmware response.
string ($date) The date selected for the upgrade to begin.
string ($date)

The date selected for 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

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.

Example Request

Schedule firmware upgrades for two devices:

      "15-digit IMEI",
      "15-digit IMEI"

Success Responses

Status 200

A successful request returns information about the scheduled upgrade and an upgrade ID that you can use 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 selected 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.

Example Success Response

  "id": "e3a8d88a-04c6-4ef3-b039-89b62f91e962",
  "accountName": "0242078689-00001",
  "firmwareName": "FOTA_Verizon_Model-A_01To02_HF",
  "firmwareTo": "VerizonFirmwareVersion-02",
  "startDate": "2018-03-05",
  "status": "RequestPending",
  "deviceList": [
          "deviceId": "15-digit IMEI",
          "status": "RequestPending"
          "deviceId": "15-digit IMEI",
          "status": "RequestPending"

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.