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.

Schedule a Firmware Upgrade:
POST /upgrades

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 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
Authorization required	string	HTTP Authorization request header containing a valid Bearer token.
VZ-M2M-Token required	string	A valid session token returned by a Connectivity Management POST /session/login request.
Content-Type required	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
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	string ($date)	The date selected for the upgrade to begin.
endDate optional	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
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.

Example Request

Schedule firmware upgrades for two devices:

{
   "accountName":"0000123456-00001",
   "firmwareName":"FOTA_Verizon_Model-A_01To02_HF",
   "startDate":"2018-04-01",
   "endDate":"2018-04-05",
   "devicelist":[
      "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.