Device Update - Import Update

Service:
Device Update
API Version:
2026-06-01

Import new update version. This is a long-running-operation; use Operation-Location response header value to check for operation status.

POST https://{endpoint}/deviceUpdate/{instanceId}/updates:import?api-version=2026-06-01

URI Parameters

Name In Required Type Description
endpoint
 path True

string (url)

The Device Update for IoT Hub account endpoint (hostname only, no protocol).
instanceId
 path True

string

The Device Update for IoT Hub account instance identifier.
api-version
 query True

string

minLength: 1

The API version to use for this operation.

Request Body

Name Type Description
updateToImport

ImportUpdateInputItem[]

The update to be imported (see schema https://json.schemastore.org/azure-deviceupdate-import-manifest-5.0.json for details).

Responses

Name Type Description
200 OK

Update

The request has succeeded.
202 Accepted

The request has been accepted for processing, but processing has not yet completed.

Headers

Operation-Location: string
Other Status Codes

ErrorResponse

An unexpected error response.

Security

OAuth2Auth

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
https://api.adu.microsoft.com/.default

Examples

DeviceUpdate_ImportUpdate

Sample request

POST https://contoso.api.adu.microsoft.com/deviceUpdate/blue/updates:import?api-version=2026-06-01

[
  {
    "importManifest": {
      "url": "http://test.blob.core.windows.net/test/uploadimportMan.json",
      "sizeInBytes": 816,
      "hashes": {
        "sha256": "O19LyyncPe1AGstOdkcmozLV8pSbBdqrE18HdYVohRc="
      }
    },
    "files": [
      {
        "filename": "file1.bin",
        "url": "http://test.blob.core.windows.net/test/upload1v5uww1q"
      },
      {
        "filename": "file2.bin",
        "url": "http://test.blob.core.windows.net/test/uploadkrmn5yw0"
      },
      {
        "filename": "file3.bin",
        "url": "http://test.blob.core.windows.net/test/uploaddq52ky5m"
      }
    ]
  }
]

Sample response

Status code:
202 
Operation-Location: /deviceUpdate/blue/updates/operations/e4491c54-916f-443d-9094-bcca546ace2f?api-version=2026-06-01
Status code:
200 
{
  "updateId": {
    "provider": "microsoft",
    "name": "adu",
    "version": "1.0.0.0"
  },
  "friendlyName": "Lab Sensor Update v1",
  "description": "Fix for critical vulnerability",
  "compatibility": [
    {
      "deviceManufacturer": "Microsoft",
      "deviceModel": "Toaster"
    }
  ],
  "instructions": {
    "steps": [
      {
        "description": "pre-install script",
        "handler": "microsoft/script:1",
        "handlerProperties": {
          "arguments": "--pre-install"
        },
        "files": [
          "configure.sh"
        ]
      },
      {
        "type": "reference",
        "updateId": {
          "provider": "microsoft",
          "name": "sensor",
          "version": "1.0"
        }
      }
    ]
  },
  "manifestVersion": "5.0",
  "importedDateTime": "2020-04-22T14:01:43.8408797-07:00",
  "createdDateTime": "2019-09-11T17:00:00-07:00",
  "etag": "\"3fed3378-0c67-47d2-b796-296962c66cbb\""
}

Definitions

Name Description
Error

Error details.
ErrorResponse

Common error response.
FileImportMetadata

Metadata describing an update file.
ImportManifestMetadata

Metadata describing the import manifest, a document which describes the files and other metadata about an update version.
ImportUpdateInputItem

Import update input item metadata.
InnerError

An object containing more specific information than the current object about the error.
Instructions

Update install instructions container.
Step

Update install instruction step.
StepType

Step type.
Update

Update metadata.
UpdateId

Update identifier.

Error

Object

Error details.

Name Type Description
code

string

Server defined error code.
details

Error[]

An array of errors that led to the reported error.
innererror

InnerError

An object containing more specific information than the current object about the error.
message

string

A human-readable representation of the error.
occurredDateTime

string (date-time)

Date and time in UTC when the error occurred.
target

string

The target of the error.

ErrorResponse

Object

Common error response.

Name Type Description
error

Error

The error details.

FileImportMetadata

Object

Metadata describing an update file.

Name Type Description
filename

string

Update file name as specified inside import manifest.
url

string

Azure Blob location from which the update file can be downloaded by Device Update for IoT Hub. This is typically a read-only SAS-protected blob URL with an expiration set to at least 4 hours.

ImportManifestMetadata

Object

Metadata describing the import manifest, a document which describes the files and other metadata about an update version.

Name Type Description
hashes

object

A JSON object containing the hash(es) of the file. At least SHA256 hash is required. This object can be thought of as a set of key-value pairs where the key is the hash algorithm, and the value is the hash of the file calculated using that algorithm.
sizeInBytes

integer (int64)

File size in number of bytes.
url

string

Azure Blob location from which the import manifest can be downloaded by Device Update for IoT Hub. This is typically a read-only SAS-protected blob URL with an expiration set to at least 4 hours.

ImportUpdateInputItem

Object

Import update input item metadata.

Name Type Description
files

FileImportMetadata[]

One or more update file properties like filename and source URL.
friendlyName

string

minLength: 1
maxLength: 512

Friendly update name.
importManifest

ImportManifestMetadata

Import manifest metadata like source URL, file size/hashes, etc.

InnerError

Object

An object containing more specific information than the current object about the error.

Name Type Description
code

string

A more specific error code than what was provided by the containing error.
errorDetail

string

The internal error or exception message.
innerError

InnerError

An object containing more specific information than the current object about the error.
message

string

A human-readable representation of the error.

Instructions

Object

Update install instructions container.

Name Type Description
steps

Step[]

Collection of installation steps.

Step

Object

Update install instruction step.

Name Type Default value Description
description

string

minLength: 1
maxLength: 64

Step description.
files

string[]

Collection of file names to be passed to handler during execution. Required if step type is inline.
handler

string

minLength: 1
maxLength: 32

Identity of handler that will execute this step. Required if step type is inline.
handlerProperties

deviceupdate.dataplane.duiothub.deviceupdate.importupdate

Parameters to be passed to handler during execution.
type

StepType

inline

Step type.
updateId

UpdateId

Referenced child update identity. Required if step type is reference.

StepType

Enumeration

Step type.

Value Description
inline

Step type that performs code execution.
reference

Step type that installs another update.

Update

Object

Update metadata.

Name Type Default value Description
compatibility

object[]

List of update compatibility information.
createdDateTime

string (date-time)

Date and time in UTC when the update was created.
description

string

minLength: 1
maxLength: 512

Update description specified by creator.
etag

string

Update ETag.
friendlyName

string

minLength: 1
maxLength: 512

Friendly update name specified by importer.
importedDateTime

string (date-time)

Date and time in UTC when the update was imported.
installedCriteria

string

String interpreted by Device Update client to determine if the update is installed on the device. Deprecated in latest import manifest schema.
instructions

Instructions

Update install instructions.
isDeployable

boolean

True

Whether the update can be deployed to a device on its own.
manifestVersion

string

Schema version of manifest used to import the update.
referencedBy

UpdateId[]

List of update identities that reference this update.
scanResult

string

Update aggregate scan result (calculated from payload file scan results).
updateId

UpdateId

Update identity.
updateType

string

Update type. Deprecated in latest import manifest schema.

UpdateId

Object

Update identifier.

Name Type Description
name

string

Update name.
provider

string

Update provider.
version

string

Update version.