Schedule a firmware upgrade

Schedule an Upgrade

`POST /campaigns/software/{accountName}`

Schedules a software upgrade for HTTP devices.

Note: Campaign time windows for downloading and installing software are available as long as the device OEM supports this. (The devices must support date windows, but the device OEM may download and install once they checked-in, provided they are in the date range.)

Uses and Requirements

This API allows you to schedule a software upgrade for HTTP devices. The response includes an upgrade ID that is included in all callback notifications about the status of the upgrade 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.

After you send a request to schedule an upgrade, the upgrade advances through several states:

CampaignRequestPending: The upgrade request has been accepted but is not scheduled yet.
- If any parameter checks fail, the state changes to CampaignRequestFailed.
CampaignQueued: The upgrade request has passed a campaign eligibility check and campaign parameters validation. The upgrade is in the queue waiting to be scheduled.
- You can cancel the campaign if it is in Queued status and if it is before the Start Date, which becomes CampaignCancelled state.
- You can delete the campaign after the start date, which becomes CampaignAborted state.
CampaignFailed: The campaign scheduling API call has failed.
CampaignScheduled: The upgrade is scheduled. This appears before the campaign start date.
- After the start date has passed and the upgrade is in progress you can abort the campaign. Some devices may have already started or completed the upgrade. Upgrades on remaining devices might not complete the upgrade.
CampaignEnded: The campaign end date has passed. No more devices are allowed to upgrade if they have checked in before the campaign end date.

If you have registered a callback URL, ThingSpace sends 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.

HTTP Request

POST https://thingspace.verizon.com/api/fota/v2/campaigns/software/{accountName}

Resource Path Parameters

Parameter Name	Data Type	Description
accountName required	string	The account name.

Header Parameters

The request header must 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}`

Request Body

The request body identifies the devices that you want to upgrade.

Parameter Name	Data Type	Description
campaignName	string	The campaign name.
softwareName required	string	The name of the software you are upgrading to.
softwareFrom required	string	The name of the old software on the device.
softwareTo required	string	The name of the new software you are upgrading to.
distributionType required	string	Valid values include: LWM2M OMA HTTP
startDate required	string($date)	Campaign start date.
endDate required	string($date)	Campaign end date.
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.
downloadAfterDate	string($date)	Specifies the starting date the client should download the package. If null, client downloads as soon as possible.
downloadTimeWindowList	Array of startTime and endTime objects	List of allowed download time windows.
downloadTimeWindowList.startTime required	integer	Start hour in range [0-23], current hour >= startTime. When the current hour falls between the startTime and the endTime, it starts.
downloadTimeWindowList.endTime required	integer	End hour in range [1-24], current hour < endTime.
installAfterDate	string($date)	The date after which you install the package. If null, install as soon as possible.
installTimeWindowList	Array of startTime and endTime objects	List of allowed install time windows.
installTimeWindowList.startTime required	integer	Start hour in range [0-23], current hour >= startTime. When the current hour falls between the startTime and the endTime, it starts.
installTimeWindowList.endTime required	integer	End hour in range [1-24], current hour < endTime.
deviceList required	Array of deviceID objects	Device IMEI list.

Example Request

Request a software upgrade.

curl https://thingspace.verizon.com/api/fota/v2/campaigns/software/$ACC -H 'Authorization: Bearer $AUTH_TOKEN' -H 'VZ-M2M-Token: $M2M_TOKEN' -H 'Content-Type: application/json' -d{  "campaignName": "FOTA_Verizon_Upgrade",  "softwareName": "FOTA_Verizon_Model-A_02To03_HF",  "softwareFrom": "FOTA_Verizon_Model-A_00To01_HF",  "softwareTo": "FOTA_Verizon_Model-A_02To03_HF",  "distributionType": "HTTP",  "startDate": "2020-08-21",  "endDate": "2020-08-22",  "autoAssignLicenseFlag": true,  "autoAddDevicesFlag": true,  "downloadAfterDate": "2020-08-21",  "downloadTimeWindowList": [    {      "startTime": 20,      "endTime": 21    }  ],  "installAfterDate": "2020-08-21",  "installTimeWindowList": [    {      "startTime": 22,      "endTime": 23    }  ],  "deviceList": [      "990013907835573",      "990013907884259"    ]}

Success Responses

Status 200

Parameter Name	Data Type	Description
id	string	Upgrade identifier.
accountName	string	The account name.
campaignName	string	The campaign name.
softwareName	string	The name of the software to which you are upgrading.
distributionType	string	Valid values include: LWM2M OMA HTTP
make	string	Applicable make.
model	string	Applicable model.
softwareFrom	string	The name of the old software on the device.
softwareTo	string	The name of the new software to which you are upgrading.
startDate	string($date)	Campaign start date.
endDate	string($date)	Campaign end date.
downloadAfterDate	string($date)	List of allowed download time windows.
downloadTimeWindowList	Array of startTime and endTime objects	Specifies the starting date the client should download the package. If null, client downloads as soon as possible.
downloadTimeWindowList.startTime	integer	Start hour in range [0-23], current hour >= startTime. When the current hour falls between the startTime and the endTime, it starts.
downloadTimeWindowList.endTime	integer	End hour in range [1-24], current hour < endTime.
autoAssignLicenseFlag	boolean	Valid values include: True and False:
autoAddDevicesFlag	boolean	Valid values include: True: and False:
installAfterDate	string($date)	The date after which client installs the package. If null, client installs as soon as possible.
installTimeWindowList	Array of startTime and endTime objects	List of allowed install time windows.
installTimeWindowList.startTime	integer	Start hour in range [0-23], current hour >= startTime. When the current hour falls between the startTime and the endTime, it starts.
installTimeWindowList.endTime	integer	End hour in range [1-24], current hour < endTime.
status	string	Software upgrade status.

Example Success Responses

{  "id": "60b5d639-ccdc-4db8-8824-069bd94c95bf",  "accountName": "0000123456-00001",  "campaignName": "FOTA_Verizon_Upgrade",  "softwareName": "FOTA_Verizon_Model-A_02To03_HF",  "distributionType": "HTTP",  "make": "Verizon",  "model": "Model-A",  "softwareFrom": "FOTA_Verizon_Model-A_00To01_HF",  "softwareTo": "FOTA_Verizon_Model-A_02To03_HF",  "startDate": "2020-08-21",  "endDate": "2020-08-22",  "autoAssignLicenseFlag": true,  "autoAddDevicesFlag": true,  "downloadAfterDate": "2020-08-21",  "downloadTimeWindowList": [    {      "startTime": 20,      "endTime": 21    }  ],  "installAfterDate": "2020-08-21",  "installTimeWindowList": [    {      "startTime": 22,      "endTime": 23    }  ],  "status": "CampaignRequestPending"}

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 an Upgrade ### `POST /campaigns/software/{accountName}` Schedules a software upgrade for HTTP devices. **Note:** Campaign time windows for downloading and installing software are available as long as the device OEM supports this. (The devices must support date windows, but the device OEM may download and install once they checked-in, provided they are in the date range.) ## Uses and Requirements This API allows you to schedule a software upgrade for HTTP devices. The response includes an upgrade ID that is included in all callback notifications about the status of the upgrade 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. After you send a request to schedule an upgrade, the upgrade advances through several states: - **CampaignRequestPending**: The upgrade request has been accepted but is not scheduled yet. - If any parameter checks fail, the state changes to **CampaignRequestFailed**. - **CampaignQueued**: The upgrade request has passed a campaign eligibility check and campaign parameters validation. The upgrade is in the queue waiting to be scheduled. - You can cancel the campaign if it is in Queued status and if it is before the Start Date, which becomes **CampaignCancelled** state. - You can delete the campaign after the start date, which becomes **CampaignAborted** state. - **CampaignFailed**: The campaign scheduling API call has failed. - **CampaignScheduled**: The upgrade is scheduled. This appears before the campaign start date. - After the start date has passed and the upgrade is in progress you can abort the campaign. Some devices may have already started or completed the upgrade. Upgrades on remaining devices might not complete the upgrade. - **CampaignEnded**: The campaign end date has passed. No more devices are allowed to upgrade if they have checked in before the campaign end date. If you have registered a callback URL, ThingSpace sends 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. ## HTTP Request [POST https://thingspace.verizon.com/api/fota/v2/campaigns/software/{accountName}](/docs/premium-apis/software-management/software-management-v2/api-endpoints/campaigns-v2/scheduleswupgradehttpdevices) ## Resource Path Parameters | Parameter Name | Data Type | Description | |:-----------------------|:-----------|:-----------------------------------------------------| | **accountName** _required_ | string | The account name. | ## Header Parameters The request header must 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}` | ## Request Body The request body identifies the devices that you want to upgrade. | Parameter Name | Data Type | Description | |:---------------------------------|:--------------------------|:-------------------------------------------------------------------------------------------------------------------------------------| | campaignName | string | The campaign name. | | softwareName _required_ | string | The name of the software you are upgrading to. | | softwareFrom _required_ | string | The name of the old software on the device. | | softwareTo _required_ | string | The name of the new software you are upgrading to. | | distributionType _required_ | string | Valid values include: <ul> <li>LWM2M</li> <li>OMA</li> <li>HTTP</li></ul> | | startDate _required_ | string($date) | Campaign start date. | | endDate _required_ | string($date) | Campaign end date. | | **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. | | downloadAfterDate | string($date) | Specifies the starting date the client should download the package. If null, client downloads as soon as possible. | | downloadTimeWindowList | Array of startTime and endTime objects | List of allowed download time windows. | | downloadTimeWindowList.startTime *required* | integer | Start hour in range [0-23], current hour >= startTime. When the current hour falls between the startTime and the endTime, it starts. | | downloadTimeWindowList.endTime *required* | integer | End hour in range [1-24], current hour < endTime. | | installAfterDate | string($date) | The date after which you install the package. If null, install as soon as possible. | | installTimeWindowList | Array of startTime and endTime objects | List of allowed install time windows. | | installTimeWindowList.startTime *required* | integer | Start hour in range [0-23], current hour >= startTime. When the current hour falls between the startTime and the endTime, it starts. | | installTimeWindowList.endTime *required* | integer | End hour in range [1-24], current hour < endTime. | | deviceList *required* | Array of deviceID objects | Device IMEI list. | ## Example Request Request a software upgrade. ```json curl https://thingspace.verizon.com/api/fota/v2/campaigns/software/$ACC -H 'Authorization: Bearer $AUTH_TOKEN' -H 'VZ-M2M-Token: $M2M_TOKEN' -H 'Content-Type: application/json' -d { "campaignName": "FOTA_Verizon_Upgrade", "softwareName": "FOTA_Verizon_Model-A_02To03_HF", "softwareFrom": "FOTA_Verizon_Model-A_00To01_HF", "softwareTo": "FOTA_Verizon_Model-A_02To03_HF", "distributionType": "HTTP", "startDate": "2020-08-21", "endDate": "2020-08-22", "autoAssignLicenseFlag": true, "autoAddDevicesFlag": true, "downloadAfterDate": "2020-08-21", "downloadTimeWindowList": [ { "startTime": 20, "endTime": 21 } ], "installAfterDate": "2020-08-21", "installTimeWindowList": [ { "startTime": 22, "endTime": 23 } ], "deviceList": [ "990013907835573", "990013907884259" ] } ``` ## Success Responses **Status 200** | Parameter Name | Data Type | Description | |:---------------------------------|:--------------|:-------------------------------------------------------------------------------------------------------------------------------------| | id | string | Upgrade identifier. | | accountName | string | The account name. | | campaignName | string | The campaign name. | | softwareName | string | The name of the software to which you are upgrading. | | distributionType | string | Valid values include: <ul> <li>LWM2M</li> <li>OMA</li> <li>HTTP</li></ul> | | make | string | Applicable make. | | model | string | Applicable model. | | softwareFrom | string | The name of the old software on the device. | | softwareTo | string | The name of the new software to which you are upgrading. | | startDate | string($date) | Campaign start date. | | endDate | string($date) | Campaign end date. | | downloadAfterDate | string($date) | List of allowed download time windows. | | downloadTimeWindowList | Array of startTime and endTime objects | Specifies the starting date the client should download the package. If null, client downloads as soon as possible. | | downloadTimeWindowList.startTime | integer | Start hour in range [0-23], current hour >= startTime. When the current hour falls between the startTime and the endTime, it starts. | | downloadTimeWindowList.endTime | integer | End hour in range [1-24], current hour < endTime. | | **autoAssignLicenseFlag** | boolean | Valid values include: **True** and **False:** | | **autoAddDevicesFlag** | boolean | Valid values include: **True:** and **False:** | | installAfterDate | string($date) | The date after which client installs the package. If null, client installs as soon as possible. | | installTimeWindowList | Array of startTime and endTime objects | List of allowed install time windows. | | installTimeWindowList.startTime | integer | Start hour in range [0-23], current hour >= startTime. When the current hour falls between the startTime and the endTime, it starts. | | installTimeWindowList.endTime | integer | End hour in range [1-24], current hour < endTime. | | status | string | Software upgrade status. | ## Example Success Responses ```json { "id": "60b5d639-ccdc-4db8-8824-069bd94c95bf", "accountName": "0000123456-00001", "campaignName": "FOTA_Verizon_Upgrade", "softwareName": "FOTA_Verizon_Model-A_02To03_HF", "distributionType": "HTTP", "make": "Verizon", "model": "Model-A", "softwareFrom": "FOTA_Verizon_Model-A_00To01_HF", "softwareTo": "FOTA_Verizon_Model-A_02To03_HF", "startDate": "2020-08-21", "endDate": "2020-08-22", "autoAssignLicenseFlag": true, "autoAddDevicesFlag": true, "downloadAfterDate": "2020-08-21", "downloadTimeWindowList": [ { "startTime": 20, "endTime": 21 } ], "installAfterDate": "2020-08-21", "installTimeWindowList": [ { "startTime": 22, "endTime": 23 } ], "status": "CampaignRequestPending" } ``` ## 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 page, along with explanations and suggestions for corrective actions.

Verizon 5G Edge API Portal

Schedule a firmware upgrade

Schedule an Upgrade

`POST /campaigns/software/{accountName}`

Uses and Requirements

HTTP Request

Resource Path Parameters

Header Parameters

Request Body

Example Request

Success Responses

Example Success Responses

Failure Responses

On this page

Schedule an Upgrade

`POST /campaigns/software/{accountName}`

Uses and Requirements

HTTP Request

Resource Path Parameters

Header Parameters

Request Body

Example Request

Success Responses

Example Success Responses

Failure Responses