Share via

Individual Enrollment - Create Or Update

  • Reference
Service:
IoT Hub Device Provisioning Service
API Version:
2021-10-01

Create or update a device enrollment record.

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

URI Parameters

Name In Required Type Description
id
 path True

string

This id is used to uniquely identify a device registration of an enrollment. A case-insensitive string (up to 128 characters long) of alphanumeric characters plus certain special characters : . _ -. No special characters allowed at start or end.
api-version
 query True

string

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

Request Header

Name Required Type Description
If-Match

string

The ETag of the enrollment record.

Request Body

Name Required Type Description
attestation True

AttestationMechanism

Attestation mechanism for individualEnrollment as well as enrollmentGroup.
registrationId True

string

This id is used to uniquely identify a device registration of an enrollment. A case-insensitive string (up to 128 characters long) of alphanumeric characters plus certain special characters : . _ -. No special characters allowed at start or end.
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

DeviceCapabilities

Device capabilities.
customAllocationDefinition

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

InitialTwin

Initial device twin. Contains a subset of the properties of 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

TwinCollection

Represents a collection of properties within a Twin
provisioningStatus enum:
  • enabled
  • disabled

The provisioning status.
registrationState

DeviceRegistrationState

Device registration state.
reprovisionPolicy

ReprovisionPolicy

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

Responses

Name Type Description
200 OK

IndividualEnrollment

Success
Other Status Codes

ProvisioningServiceErrorDetails

Error response

Headers

x-ms-error-code: string

Definitions

Name Description
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

SymmetricKeyAttestation

Attestation via SymmetricKey.
tpm

TpmAttestation

Attestation via TPM.
type enum:
  • none
  • symmetricKey
  • tpm
  • x509

Attestation Type.
x509

X509Attestation

Attestation via X509.

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 Default value Description
iotEdge

boolean

False

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

registrationId

string

This id is used to uniquely identify a device registration of an enrollment. A case-insensitive string (up to 128 characters long) of alphanumeric characters plus certain special characters : . _ -. No special characters allowed at start or end.
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 Default value 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

AttestationMechanism

Attestation mechanism for individualEnrollment as well as enrollmentGroup.
capabilities

DeviceCapabilities

Device capabilities.
createdDateTimeUtc

string

The DateTime this resource was created.
customAllocationDefinition

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

InitialTwin

Initial device twin. Contains a subset of the properties of 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

TwinCollection

Represents a collection of properties within a Twin
provisioningStatus enum:
  • disabled
  • enabled
enabled

The provisioning status.
registrationId

string

This id is used to uniquely identify a device registration of an enrollment. A case-insensitive string (up to 128 characters long) of alphanumeric characters plus certain special characters : . _ -. No special characters allowed at start or end.
registrationState

DeviceRegistrationState

Device registration state.
reprovisionPolicy

ReprovisionPolicy

The behavior of the service 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

InitialTwinProperties

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

TwinCollection

Represents a collection of properties within a Twin

InitialTwinProperties

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

Name Type Description
desired

TwinCollection

Represents a collection of properties within a Twin

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 Default value Description
migrateDeviceData

boolean

True

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

True

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

Metadata for the TwinCollection
version

integer

Version of the TwinCollection

X509Attestation

Attestation via X509.

Name Type Description
caReferences

X509CAReferences

Primary and secondary CA references.
clientCertificates

X509Certificates

Primary and secondary certificates
signingCertificates

X509Certificates

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

X509CertificateWithInfo

Certificate and Certificate info
secondary

X509CertificateWithInfo

Certificate and Certificate info

X509CertificateWithInfo

Certificate and Certificate info

Name Type Description
certificate

string

info

X509CertificateInfo

X509 certificate info.