Individual Enrollment - Create Or Update

Create or update a device enrollment record.

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

URI Parameters

Name In Required Type Description
dpsName
path True

string

The DPS instance hostname.

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

minLength: 1

The API version to use for this operation.

Request Header

Name Required Type Description
Authorization True

string

If-Match

string

The ETag of the enrollment record.

Request Body

Name Required Type Description
attestation True

AttestationMechanism

Attestation method used by the device.

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

AllocationPolicy

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

Capabilities of the device.

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.

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

Optional Device Information.

provisioningStatus

ProvisioningStatus

The provisioning status.

reprovisionPolicy

ReprovisionPolicy

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

Responses

Name Type Description
200 OK

IndividualEnrollment

The request has succeeded.

Other Status Codes

ProvisioningServiceErrorDetails

An unexpected error response.

Headers

x-ms-error-code: string

Security

Authorization

Type: apiKey
In: header

Examples

IndividualEnrollment_CreateOrUpdate_MaximumSet_Gen
IndividualEnrollment_CreateOrUpdate_MinimumSet_Gen

IndividualEnrollment_CreateOrUpdate_MaximumSet_Gen

Sample request

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


{
  "allocationPolicy": "hashed",
  "attestation": {
    "type": "none",
    "symmetricKey": {
      "primaryKey": "tdoshkmlo",
      "secondaryKey": "lmajoyzuojahffcmdlcwjhntqzyqzk"
    },
    "tpm": {
      "endorsementKey": "naoofgjbxiulcitlysusxdvagyucgn",
      "storageRootKey": "tdgkgcvptrsw"
    },
    "x509": {
      "caReferences": {
        "primary": "efbkbboxkvrsdl",
        "secondary": "vckhuzqgbcinighxwyuyd"
      },
      "clientCertificates": {
        "primary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        },
        "secondary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        }
      },
      "signingCertificates": {
        "primary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        },
        "secondary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        }
      }
    }
  },
  "capabilities": {
    "iotEdge": true
  },
  "customAllocationDefinition": {
    "apiVersion": "gbannxdstouqrfonxdxfurv",
    "webhookUrl": "todqbubyxeumrtvhsscedwrkz"
  },
  "deviceId": "wfgzhrgpvmwddrknnmcggbae",
  "etag": "ngtrmhcikthymtknva",
  "initialTwin": {
    "properties": {
      "desired": {
        "count": 16,
        "key2428": {},
        "metadata": {
          "lastUpdated": "2025-10-01T17:42:04.76Z",
          "lastUpdatedVersion": 19
        },
        "version": 9
      }
    },
    "tags": {
      "count": 16,
      "key2428": {},
      "metadata": {
        "lastUpdated": "2025-10-01T17:42:04.76Z",
        "lastUpdatedVersion": 19
      },
      "version": 9
    }
  },
  "iotHubHostName": "vtewercilhukfboi",
  "iotHubs": [
    "lwgwrfdherfrbowfdbrdhvnragwrs"
  ],
  "optionalDeviceInformation": {
    "count": 16,
    "key2428": {},
    "metadata": {
      "lastUpdated": "2025-10-01T17:42:04.76Z",
      "lastUpdatedVersion": 19
    },
    "version": 9
  },
  "provisioningStatus": "enabled",
  "registrationId": "kz",
  "registrationState": {},
  "reprovisionPolicy": {
    "migrateDeviceData": true,
    "updateHubAssignment": true
  }
}

Sample response

{
  "allocationPolicy": "hashed",
  "attestation": {
    "type": "none",
    "symmetricKey": {
      "primaryKey": "tdoshkmlo",
      "secondaryKey": "lmajoyzuojahffcmdlcwjhntqzyqzk"
    },
    "tpm": {
      "endorsementKey": "naoofgjbxiulcitlysusxdvagyucgn",
      "storageRootKey": "tdgkgcvptrsw"
    },
    "x509": {
      "caReferences": {
        "primary": "efbkbboxkvrsdl",
        "secondary": "vckhuzqgbcinighxwyuyd"
      },
      "clientCertificates": {
        "primary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        },
        "secondary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        }
      },
      "signingCertificates": {
        "primary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        },
        "secondary": {
          "info": {
            "issuerName": "pkuinyhttjlozsbtvxuizzkjlakga",
            "notAfterUtc": "2025-10-01T17:42:04.76Z",
            "notBeforeUtc": "2025-10-01T17:42:04.76Z",
            "serialNumber": "mzoidcxayenpgyrek",
            "sha1Thumbprint": "fdmftjqllzvxcd",
            "sha256Thumbprint": "ei",
            "subjectName": "qqjdjgrkiqvtnshkisozut",
            "version": 12
          },
          "certificate": "gkozpt"
        }
      }
    }
  },
  "capabilities": {
    "iotEdge": true
  },
  "createdDateTimeUtc": "2025-10-01T17:42:04.76Z",
  "customAllocationDefinition": {
    "apiVersion": "gbannxdstouqrfonxdxfurv",
    "webhookUrl": "todqbubyxeumrtvhsscedwrkz"
  },
  "deviceId": "wfgzhrgpvmwddrknnmcggbae",
  "etag": "ngtrmhcikthymtknva",
  "initialTwin": {
    "properties": {
      "desired": {
        "count": 16,
        "key2428": {},
        "metadata": {
          "lastUpdated": "2025-10-01T17:42:04.76Z",
          "lastUpdatedVersion": 19
        },
        "version": 9
      }
    },
    "tags": {
      "count": 16,
      "key2428": {},
      "metadata": {
        "lastUpdated": "2025-10-01T17:42:04.76Z",
        "lastUpdatedVersion": 19
      },
      "version": 9
    }
  },
  "iotHubHostName": "vtewercilhukfboi",
  "iotHubs": [
    "lwgwrfdherfrbowfdbrdhvnragwrs"
  ],
  "lastUpdatedDateTimeUtc": "2025-10-01T17:42:04.76Z",
  "optionalDeviceInformation": {
    "count": 16,
    "key2428": {},
    "metadata": {
      "lastUpdated": "2025-10-01T17:42:04.76Z",
      "lastUpdatedVersion": 19
    },
    "version": 9
  },
  "provisioningStatus": "enabled",
  "registrationId": "kz",
  "registrationState": {
    "assignedHub": "oasugtinnefgfklhldjhibq",
    "createdDateTimeUtc": "2025-10-01T17:42:04.759Z",
    "deviceId": "ttnhaugyyh",
    "errorCode": 2,
    "errorMessage": "ufqpjjmbiphiynoijjbocvl",
    "etag": "ctquvtjyhnomcmtddscxwjk",
    "lastUpdatedDateTimeUtc": "2025-10-01T17:42:04.759Z",
    "payload": {},
    "registrationId": "czvnrxvbka",
    "status": "unassigned",
    "substatus": "initialAssignment"
  },
  "reprovisionPolicy": {
    "migrateDeviceData": true,
    "updateHubAssignment": true
  }
}

IndividualEnrollment_CreateOrUpdate_MinimumSet_Gen

Sample request

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

{
  "attestation": {
    "type": "none"
  },
  "registrationId": "kz"
}

Sample response

{
  "attestation": {
    "type": "none"
  },
  "registrationId": "kz"
}

Definitions

Name Description
AllocationPolicy

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.

AssignedDeviceSubstatus

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.

AttestationMechanism

Attestation mechanism for individualEnrollment as well as enrollmentGroup.

AttestationType

Attestation Type.

CustomAllocationDefinition

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

DeviceCapabilities

Device capabilities.

DeviceRegistrationState

Device registration state.

EnrollmentStatus

Enrollment status.

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.

ProvisioningStatus

The provisioning status.

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

AllocationPolicy

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.

Value Description
hashed

hashed

geoLatency

geoLatency

static

static

custom

custom

AssignedDeviceSubstatus

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.

Value Description
initialAssignment

initialAssignment

deviceDataMigrated

deviceDataMigrated

deviceDataReset

deviceDataReset

reprovisionedToInitialAssignment

reprovisionedToInitialAssignment

AttestationMechanism

Attestation mechanism for individualEnrollment as well as enrollmentGroup.

Name Type Description
symmetricKey

SymmetricKeyAttestation

Symmetric Key attestation method.

tpm

TpmAttestation

TPM attestation method.

type

AttestationType

Attestation Type.

x509

X509Attestation

X509 attestation method.

AttestationType

Attestation Type.

Value Description
none

none

tpm

tpm

x509

x509

symmetricKey

symmetricKey

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 (date-time)

Registration create date time (in UTC).

deviceId

string

Device ID.

errorCode

integer (int32)

Error code.

errorMessage

string

Error message.

etag

string

The entity tag associated with the resource.

lastUpdatedDateTimeUtc

string (date-time)

Last updated date time (in UTC).

payload

Custom allocation payload returned from the webhook to the device.

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

EnrollmentStatus

Enrollment status.

substatus

AssignedDeviceSubstatus

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.

EnrollmentStatus

Enrollment status.

Value Description
unassigned

unassigned

assigning

assigning

assigned

assigned

failed

failed

disabled

disabled

IndividualEnrollment

The device enrollment record.

Name Type Default value Description
allocationPolicy

AllocationPolicy

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 method used by the device.

capabilities

DeviceCapabilities

Capabilities of the device.

createdDateTimeUtc

string (date-time)

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.

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 (date-time)

The DateTime this resource was last updated.

optionalDeviceInformation

TwinCollection

Optional Device Information.

provisioningStatus

ProvisioningStatus

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

Current registration status.

reprovisionPolicy

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

InitialTwinProperties

Twin desired properties.

tags

TwinCollection

Twin tags.

InitialTwinProperties

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

Name Type Description
desired

TwinCollection

Gets and sets the InitialTwin desired properties.

Metadata

Metadata for the TwinCollection

Name Type Description
lastUpdated

string (date-time)

Last time the TwinCollection was updated

lastUpdatedVersion

integer (int32)

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 (int32)

Error code for the operation.

info

object

Dictionary of <string>

message

string

Human-readable error message.

timestampUtc

string (date-time)

UTC timestamp of the error.

trackingId

string

Tracking ID for the error.

ProvisioningStatus

The provisioning status.

Value Description
enabled

enabled

disabled

disabled

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

TPM endorsement key.

storageRootKey

string

TPM storage root key.

TwinCollection

Represents a collection of properties within a Twin

Name Type Description
count

integer (int32)

Number of properties in the TwinCollection

metadata

Metadata

Metadata for the TwinCollection

version

integer (int32)

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

Primary CA reference.

secondary

string

Secondary CA reference.

X509CertificateInfo

X509 certificate info.

Name Type Description
issuerName

string

Issuer name of the certificate.

notAfterUtc

string (date-time)

Certificate validity end (UTC).

notBeforeUtc

string (date-time)

Certificate validity start (UTC).

serialNumber

string

Serial number of the certificate.

sha1Thumbprint

string

SHA-1 thumbprint of the certificate.

sha256Thumbprint

string

SHA-256 thumbprint of the certificate.

subjectName

string

Subject name of the certificate.

version

integer (int32)

Version of the certificate.

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

PEM-formatted certificate string.

info

X509CertificateInfo

X509 certificate info.