Schedule a firmware upgrade

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": true

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.

# 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](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/working-with-verizon-wireless/about-callback-services), 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](https://thingspace.verizon.com/documentation/api-documentation.html#/http/session-management/guides/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](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/api-endpoints/device-management/list-devices-information) 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: ```json 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 ```json "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": true ``` ## Failure Responses **Status 400** All error messages are returned in this format: ```json { "errorCode": "error code string", "errorMessage": "error message string" } ``` Error codes and messages are listed on the [Error Messages](https://thingspace.verizon.com/documentation/api-documentation.html#/http/software-management/guides/error-messages) page, along with explanations and suggestions for corrective actions.

Verizon 5G Edge API Portal

Schedule a firmware upgrade