Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

StartDeviceDiscovery

This API is used to start device discovery for hub-connected and third-party-connected devices. The authentication material (install code) is delivered as a message to the controller instructing it to start the discovery.

Request Syntax


POST /device-discoveries HTTP/1.1
Content-type: application/json

{
   "AccountAssociationId": "string",
   "AuthenticationMaterial": "string",
   "AuthenticationMaterialType": "string",
   "ClientToken": "string",
   "ConnectorAssociationIdentifier": "string",
   "ControllerIdentifier": "string",
   "CustomProtocolDetail": { 
      "string" : "string" 
   },
   "DiscoveryType": "string",
   "Tags": { 
      "string" : "string" 
   }
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

AccountAssociationId

The identifier of the cloud-to-cloud account association to use for discovery of third-party devices.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [0-9a-zA-Z]+

Required: No

AuthenticationMaterial

The authentication material required to start the local device discovery job request.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [0-9A-Za-z_\-\+=\/:; ]+

Required: No

AuthenticationMaterialType

The type of authentication material used for device discovery jobs.

Type: String

Valid Values: ZWAVE_INSTALL_CODE

Required: No

ClientToken

An idempotency token. If you retry a request that completed successfully initially using the same client token and parameters, then the retry attempt will succeed without performing any further actions.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [a-zA-Z0-9=_-]+

Required: No

ConnectorAssociationIdentifier

This parameter has been deprecated.

The id of the connector association.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [0-9a-zA-Z]+

Required: No

ControllerIdentifier

The id of the end-user's IoT hub.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [a-zA-Z0-9:_-]*

Required: No

CustomProtocolDetail

Additional protocol-specific details required for device discovery, which vary based on the discovery type.

Note

For a DiscoveryType of CUSTOM, the string-to-string map must have a key value of Name set to a non-empty-string.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 256.

Key Pattern: [a-zA-Z0-9 _.-]+

Value Length Constraints: Minimum length of 1. Maximum length of 512.

Value Pattern: [a-zA-Z0-9 _.{}:"-]+

Required: No

DiscoveryType

The discovery type supporting the type of device to be discovered in the device discovery task request.

Type: String

Valid Values: ZWAVE | ZIGBEE | CLOUD | CUSTOM

Required: Yes

Tags

This parameter has been deprecated.

A set of key/value pairs that are used to manage the device discovery request.

Type: String to string map

Map Entries: Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Value Length Constraints: Minimum length of 0. Maximum length of 256.

Required: No

Response Syntax


HTTP/1.1 201
Content-type: application/json

{
   "Id": "string",
   "StartedAt": number
}

Response Elements

If the action is successful, the service sends back an HTTP 201 response.

The following data is returned in JSON format by the service.

Id

The id of the device discovery job request.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: [A-Za-z0-9]+

StartedAt

The timestamp value for the start time of the device discovery.

Type: Timestamp

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

User is not authorized.

HTTP Status Code: 403

ConflictException

There is a conflict with the request.

HTTP Status Code: 409

InternalServerException

Internal error from the service that indicates an unexpected error or that the service is unavailable.

HTTP Status Code: 500

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 404

ServiceUnavailableException

The service is temporarily unavailable.

HTTP Status Code: 503

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 429

UnauthorizedException

You are not authorized to perform this operation.

HTTP Status Code: 401

ValidationException

A validation error occurred when performing the API request.

HTTP Status Code: 400