Claim Device

Time	Status	User Agent
Retrieving recent requests…

Overview

The Claim Device API allows claiming an existing device to a tenant in Xyte. The claiming flow depends on the "Authentication Method" of the claimed device, that can be either "Serial Number & MAC Address" or "CloudID" based. As such only SN & MAC or CloudID should be specified.

The space_id field is required, as it is used to determine under which "Customer" the device should be claimed (devices cannot be moved between Customers within a tenant).

Authorization

This endpoint requires Authorization.

Request data

Key	Type	Description	Required
name	string	Name of the device	No
space_id	string	ID of the space that will claim the device	Yes
mac	string	MAC address of the device. The serial number and MAC address or the Device Cloud ID is required	No
sn	string	Serial number of the device. The serial number and MAC address or the Device Cloud ID is required	No
cloud_id	string	Cloud ID of the device. The serial number and MAC address or the Device Cloud ID is required	Yes

Request

Key	Type	Description	Required
name	string	Name of the device.	No
space_id	string	ID of the space that will claim the device.	Yes
mac	string	MAC address of the device. The serial number and MAC address or the Device Cloud ID is required.	No
sn	string	Serial number of the device. The serial number and MAC address or the Device Cloud ID is required.	No
cloud_id	string	Cloud ID of the device. The serial number and MAC address or the Device Cloud ID is required.	Yes

Request sample

{
  "space_id": "xxxxx",
  "name": "DSP-X200",
  "mac": "....",
  "sn": "...",
  "cloud_id": "LelJ5pO..."
}

Response

status vs effective_status
status is the device's own reported operational state (online / offline / error).
effective_status is the aggregated health view shown in the Xyte UI. It combines the
raw status with active incidents, connectivity to the integration/proxy, and the
parent device's state. Use effective_status when you want the same health signal
users see in the dashboard; use status when you only care about the device's
self-reported state.

Key	Subkey	Type	Description
id		string	Unique identifier of the device. It is a universally unique identifier (UUID).
name		string	Name of the device.
sn		string	Serial number of the device.
mac		string	Cloud ID of the device.
cloud_id		string	Unique identifier of the device in the cloud.
status		string	Device's self-reported operational state: `online`, `offline`, `error`.
effective_status		string	Aggregated health status shown in the Xyte UI, derived from `status`, active incidents, and connectivity. One of: `ok`, `warning`, `error`, `offline`, `disconnected`, `never_seen`. `null` until first computed.
last_seen_at		string	Timestamp of the last time the device was seen online in ISO 8601 format (e.g., "2024-07-29T10:18:39.267Z").
details		object	Additional details about the device. This field might be null if no details are available.
model		object	Information about the device model.
	id	string	Unique identifier of the device model. It is a universally unique identifier (UUID).
	name	string	Name of the device model.
	sub_model	string	Sub-model of the device. This field might be null if no sub-model exists.
	beta	boolean	Whether the device model is in beta.
firmware		object	Firmware information.
	version	string	Current firmware version of the device.
space		object	Information about the space that claimed the device.
	id	integer	Unique identifier of the space where the device is located.
	full_path	string	Full path of the space where the device is located. This path represents the hierarchical structure of the space.

Example JSON Response

{
  "id": "1ad4e4e4-99b4-48ed-be81-c4....",
  "name": "DSP-X200",
  "sn": "5pOLfS-YyeE4QlKnA...",
  "mac": null,
  "cloud_id": "LelJ5pOLfS-YyeE4Q...",
  "status": "online",
  "effective_status": "ok",
  "last_seen_at": "2024-07-29T10:18:39.267Z",
  "details": null,
  "model": {
    "id": "799d6127-71b1-45af-8bca-3ad2d...",
    "name": "DSP-X200",
    "sub_model": null,
    "beta": false
  },
  "firmware": {
    "version": "1.0.0"
  },
  "space": {
    "id": "xxxxx",
    "full_path": "Green Energy Corp/United Kingdom/London/Executive Suite"
  }
}