Individual Enrollment - Create Or Update

Create or update a device enrollment record.

PUT https://your-dps.azure-devices-provisioning.net/enrollments/{id}?api-version=2021-06-01

URI Parameters

Name In Required Type Description
id
path True
  • string

The registration ID is alphanumeric, lowercase, and may contain hyphens.

api-version
query True
  • string

The API version to use for the request. Supported versions include: 2021-06-01

Request Header

Name Required Type Description
If-Match
  • string

The ETag of the enrollment record.

Request Body

Name Required Type Description
attestation True

Attestation method used by the device.

registrationId True
  • string

The registration ID is alphanumeric, lowercase, and may contain hyphens.

allocationPolicy enum:
  • hashed
  • geoLatency
  • static
  • custom

The allocation policy of this resource. This policy overrides the tenant level allocation policy for this individual enrollment or enrollment group. Possible values include 'hashed': Linked IoT hubs are equally likely to have devices provisioned to them, 'geoLatency': Devices are provisioned to an IoT hub with the lowest latency to the device.If multiple linked IoT hubs would provide the same lowest latency, the provisioning service hashes devices across those hubs, 'static' : Specification of the desired IoT hub in the enrollment list takes priority over the service-level allocation policy, 'custom': Devices are provisioned to an IoT hub based on your own custom logic. The provisioning service passes information about the device to the logic, and the logic returns the desired IoT hub as well as the desired initial configuration. We recommend using Azure Functions to host your logic.

capabilities

Capabilities of the device.

customAllocationDefinition

This tells DPS which webhook to call when using custom allocation.

deviceId
  • string

Desired IoT Hub device ID (optional).

etag
  • string

The entity tag associated with the resource.

initialTwin

Initial device twin.

iotHubHostName
  • string

The Iot Hub host name.

iotHubs
  • string[]

The list of IoT Hub hostnames the device(s) in this resource can be allocated to. Must be a subset of tenant level list of IoT hubs.

optionalDeviceInformation

Optional Device Information.

provisioningStatus enum:
  • enabled
  • disabled

The provisioning status.

reprovisionPolicy

The behavior when a device is re-provisioned to an IoT hub.

Responses

Name Type Description
200 OK

Success

Other Status Codes

Error response

Definitions

AttestationMechanism

Attestation mechanism for individualEnrollment as well as enrollmentGroup.

CustomAllocationDefinition

This tells DPS which webhook to call when using custom allocation.

DeviceCapabilities

Device capabilities.

DeviceRegistrationState

Device registration state.

IndividualEnrollment

The device enrollment record.

InitialTwin

Initial device twin. Contains a subset of the properties of Twin.

InitialTwinProperties

Represents the initial properties that will be set on the device twin.

Metadata

Metadata for the TwinCollection

ProvisioningServiceErrorDetails

Contains the properties of an error returned by the Azure IoT Hub Provisioning Service.

ReprovisionPolicy

The behavior of the service when a device is re-provisioned to an IoT hub.

SymmetricKeyAttestation

Attestation via SymmetricKey.

TpmAttestation

Attestation via TPM.

TwinCollection

Represents a collection of properties within a Twin

X509Attestation

Attestation via X509.

X509CAReferences

Primary and secondary CA references.

X509CertificateInfo

X509 certificate info.

X509Certificates

Primary and secondary certificates

X509CertificateWithInfo

Certificate and Certificate info

AttestationMechanism

Attestation mechanism for individualEnrollment as well as enrollmentGroup.

Name Type Description
symmetricKey

Symmetric Key attestation method.

tpm

TPM attestation method.

type enum:
  • none
  • symmetricKey
  • tpm
  • x509

Attestation Type.

x509

X509 attestation method.

CustomAllocationDefinition

This tells DPS which webhook to call when using custom allocation.

Name Type Description
apiVersion
  • string

The API version of the provisioning service types (such as IndividualEnrollment) sent in the custom allocation request. Minimum supported version: "2018-09-01-preview".

webhookUrl
  • string

The webhook URL used for allocation requests.

DeviceCapabilities

Device capabilities.

Name Type Description
iotEdge
  • boolean

If set to true, this device is an IoTEdge device.

DeviceRegistrationState

Device registration state.

Name Type Description
assignedHub
  • string

Assigned Azure IoT Hub.

createdDateTimeUtc
  • string

Registration create date time (in UTC).

deviceId
  • string

Device ID.

errorCode
  • integer

Error code.

errorMessage
  • string

Error message.

etag
  • string

The entity tag associated with the resource.

lastUpdatedDateTimeUtc
  • string

Last updated date time (in UTC).

payload
  • object

Custom allocation payload returned from the webhook to the device.

registrationId
  • string

The registration ID is alphanumeric, lowercase, and may contain hyphens.

status enum:
  • assigned
  • assigning
  • disabled
  • failed
  • unassigned

Enrollment status.

substatus enum:
  • deviceDataMigrated
  • deviceDataReset
  • initialAssignment
  • reprovisionedToInitialAssignment

Substatus for 'Assigned' devices. Possible values include - 'initialAssignment': Device has been assigned to an IoT hub for the first time, 'deviceDataMigrated': Device has been assigned to a different IoT hub and its device data was migrated from the previously assigned IoT hub. Device data was removed from the previously assigned IoT hub, 'deviceDataReset': Device has been assigned to a different IoT hub and its device data was populated from the initial state stored in the enrollment. Device data was removed from the previously assigned IoT hub, 'reprovisionedToInitialAssignment': Device has been re-provisioned to a previously assigned IoT hub.

IndividualEnrollment

The device enrollment record.

Name Type Description
allocationPolicy enum:
  • custom
  • geoLatency
  • hashed
  • static

The allocation policy of this resource. This policy overrides the tenant level allocation policy for this individual enrollment or enrollment group. Possible values include 'hashed': Linked IoT hubs are equally likely to have devices provisioned to them, 'geoLatency': Devices are provisioned to an IoT hub with the lowest latency to the device.If multiple linked IoT hubs would provide the same lowest latency, the provisioning service hashes devices across those hubs, 'static' : Specification of the desired IoT hub in the enrollment list takes priority over the service-level allocation policy, 'custom': Devices are provisioned to an IoT hub based on your own custom logic. The provisioning service passes information about the device to the logic, and the logic returns the desired IoT hub as well as the desired initial configuration. We recommend using Azure Functions to host your logic.

attestation

Attestation method used by the device.

capabilities

Capabilities of the device.

createdDateTimeUtc
  • string

The DateTime this resource was created.

customAllocationDefinition

This tells DPS which webhook to call when using custom allocation.

deviceId
  • string

Desired IoT Hub device ID (optional).

etag
  • string

The entity tag associated with the resource.

initialTwin

Initial device twin.

iotHubHostName
  • string

The Iot Hub host name.

iotHubs
  • string[]

The list of IoT Hub hostnames the device(s) in this resource can be allocated to. Must be a subset of tenant level list of IoT hubs.

lastUpdatedDateTimeUtc
  • string

The DateTime this resource was last updated.

optionalDeviceInformation

Optional Device Information.

provisioningStatus enum:
  • disabled
  • enabled

The provisioning status.

registrationId
  • string

The registration ID is alphanumeric, lowercase, and may contain hyphens.

registrationState

Current registration status.

reprovisionPolicy

The behavior when a device is re-provisioned to an IoT hub.

InitialTwin

Initial device twin. Contains a subset of the properties of Twin.

Name Type Description
properties

Twin desired properties.

tags

Twin tags.

InitialTwinProperties

Represents the initial properties that will be set on the device twin.

Name Type Description
desired

Gets and sets the InitialTwin desired properties.

Metadata

Metadata for the TwinCollection

Name Type Description
lastUpdated
  • string

Last time the TwinCollection was updated

lastUpdatedVersion
  • integer

This is null for reported properties metadata and is not null for desired properties metadata.

ProvisioningServiceErrorDetails

Contains the properties of an error returned by the Azure IoT Hub Provisioning Service.

Name Type Description
errorCode
  • integer
info
  • object
message
  • string
timestampUtc
  • string
trackingId
  • string

ReprovisionPolicy

The behavior of the service when a device is re-provisioned to an IoT hub.

Name Type Description
migrateDeviceData
  • boolean

When set to true (default), the Device Provisioning Service will migrate the device's data (twin, device capabilities, and device ID) from one IoT hub to another during an IoT hub assignment update. If set to false, the Device Provisioning Service will reset the device's data to the initial desired configuration stored in the corresponding enrollment list.

updateHubAssignment
  • boolean

When set to true (default), the Device Provisioning Service will evaluate the device's IoT Hub assignment and update it if necessary for any provisioning requests beyond the first from a given device. If set to false, the device will stay assigned to its current IoT hub.

SymmetricKeyAttestation

Attestation via SymmetricKey.

Name Type Description
primaryKey
  • string

Primary symmetric key.

secondaryKey
  • string

Secondary symmetric key.

TpmAttestation

Attestation via TPM.

Name Type Description
endorsementKey
  • string
storageRootKey
  • string

TwinCollection

Represents a collection of properties within a Twin

Name Type Description
count
  • integer

Number of properties in the TwinCollection

metadata

Metadata for the TwinCollection

version
  • integer

Version of the TwinCollection

X509Attestation

Attestation via X509.

Name Type Description
caReferences

Primary and secondary CA references.

clientCertificates

Primary and secondary certificates

signingCertificates

Primary and secondary certificates

X509CAReferences

Primary and secondary CA references.

Name Type Description
primary
  • string
secondary
  • string

X509CertificateInfo

X509 certificate info.

Name Type Description
issuerName
  • string
notAfterUtc
  • string
notBeforeUtc
  • string
serialNumber
  • string
sha1Thumbprint
  • string
sha256Thumbprint
  • string
subjectName
  • string
version
  • integer

X509Certificates

Primary and secondary certificates

Name Type Description
primary

Certificate and Certificate info

secondary

Certificate and Certificate info

X509CertificateWithInfo

Certificate and Certificate info

Name Type Description
certificate
  • string
info

X509 certificate info.