Schedule a firmware upgrade

POST /campaigns/software/{accountName}Copy Anchor Link

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 RequirementsCopy Anchor Link

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 RequestCopy Anchor Link

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

Resource Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

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.

Request BodyCopy Anchor Link

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

Example RequestCopy Anchor Link

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 ResponsesCopy Anchor Link

Status 200

Example Success ResponsesCopy Anchor Link

{
  "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 ResponsesCopy Anchor Link

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.