Claims a device

put

https://tracking.hereapi.com/registry/v2/devices/{deviceOrExternalId}

Claims a device, associating a device to a user account. The user who claimed a device is the device owner, which is different from the device vendor.

Unclaimed devices cannot login or send any data to HERE Tracking. A claimed device data is stored in HERE Tracking and is available to the device owner's project, which the device has been claimed to.

When a device is claimed, it gets assigned a trackingId. This is a unique ID associated with the device data in HERE Tracking.

trackingId is different from the deviceId. The deviceId is permanently associated with the hardware, while the trackingId is associated with the device data. If the device is later sold or transferred, the deviceId remains the same but the trackingId changes in case the device is reclaimed. This way the new owner cannot access the old data.

If the user is a member of multiple projects, the target project ID needs to be specified in the projectId query parameter (note that this is different from the appId).

Only users with a valid HERE Tracking license are authorized to claim new devices. Claimed devices are associated with the owner application ID, and the total device count is kept up-to-date for billing purposes.

Path Params

deviceOrExternalId

string

required

length between 1 and 50

Device ID of a provisioned physical device or for virtual devices an application specific external ID provided together with appId query parameter.

NOTE that physical devices are deprecated and they should no longer be created.

Query Params

projectId

string

length between 1 and 50

Project ID. Any HERE Tracking user must be a member of a Tracking project. The project ID can be implicitly resolved if the user calling the API is a member of a single project. If the user is a member of multiple projects, the projectId query parameter needs to be specified explicitly.

appId

string

length ≥ 8

Application identifier. Used together with an external ID to identify a virtual device.

Body Params

ownerAppId

string

length ≥ 8

(Deprecated) Application identifier which specifies device owner's application to which the device is associated with.

Headers

X-Request-Id

uuid

ID used for correlating requests within HERE Tracking. Used for logging and error reporting.

Must be a valid UUIDv4.

Responses

200Already claimed by the same user

201Successfully claimed

400Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body.

401Unauthorized The request did not provide correct authentication details

403Forbidden The account does not have the correct privileges

404Not Found The specified resource was not found

409Conflict The specified resource already exists