Accounts & Resources
An Enterprise Account is the root structure which enables you to organize and manage all of your IoT resources. This includes locations, physical spaces, devices, and members (users). The account structure allows you to manage access to those resources using defined roles with associated permissions. Below, we take a look at the entities nested beneath an Enterprise Account and how they can be utilized to meet your management needs.
Location Groups
Location Groups allow you to group and organize your Locations, including the devices, routines, and automations, associated with each Location.
Location Groups are exclusive to SmartThings Enterprise, intended to simplify how your integration interacts with larger quantities of resources by narrowing the scope of your API requests. This aligns well if you have multiple physical locations that require different levels of access or more granular permissions across the resources within those Location Groups.
Location Groups Suggested Usage
While the account structure provides flexibility in how you organize your resources, SmartThings provides suggestions on the mapping of those resources to the Enterprise Account structure. Location Groups can be a geographic area where you have a concentrated presence of physical locations like retail stores, or the physical locations themselves ie. property buildings for multi-family residences or multi-building corporate complexes. Understanding the other aspects of the account hierarchy will help you decide the best approach for your needs.
Hierarchy of an Enterprise Location Group
Location Groups are hierarchical children of Accounts, defined by the parent
object. When creating a Location Group, you must do so using an Account-level role. The create request's parent
model must correlate to a valid accountId
.
Create and Manage Location Groups
See the Location Groups API documentation for details on managing Location Groups.
Locations
Locations exist beneath Location Groups, serving as the next step down in the hierarchy. Locations serve as a virtual space where you can manage your connected devices, automations, and routines. You can learn more about Locations and their function on the SmartThings platform by visiting the SmartThings developer documentation.
Depending on your implementation of Location Groups and your business needs, a Location could map to individual physical locations, or to individual units within a physical location. Below are some examples of Locations, building on the examples provided in Location Groups.
Create a Location
Key factors in creating an Enterprise Location:
- Specify the parent Location Group (
locationGroupId
) by type & identifier - Align the Location's
countryCode
to the root Account'sregion
- Location Regionality
- Location Parent
{
"name": "Home",
"countryCode": "USA",
"latitude": 45.00708112,
"longitude": -93.11223629,
"regionRadius": 150,
"temperatureScale": "F",
"timeZoneId": "America/Chicago",
"locale": "en",
"parent": {
"type": "LOCATIONGROUP",
"id": "6ecb6c06-7319-49b1-8ebd-f97660efdd06"
}
}
{
"name": "Home",
"countryCode": "USA",
"latitude": 45.00708112,
"longitude": -93.11223629,
"regionRadius": 150,
"temperatureScale": "F",
"timeZoneId": "America/Chicago",
"locale": "en",
"parent": {
"type": "LOCATIONGROUP",
"id": "6ecb6c06-7319-49b1-8ebd-f97660efdd06"
}
}
Rooms
Rooms are an optional concept within SmartThings Locations, and can be used to help better define the physical spaces that Devices are located in. Rooms can be used to further organize and group devices in a Location, improving end user experience by creating an intuitive space for users to find and control devices. You can learn more about Rooms in the SmartThings developer documentation.
Manage Rooms and their Devices
To protect the layout structure of your SmartThings Enterprise resources, most end users lack the permission to create or modify Rooms. In this case, customization of Rooms (and the devices therein) must be managed through your Enterprise integration.
SmartThings provides APIs to manage rooms and their devices, allowing your integration to create, read, update, and delete.
- For each residential unit, obtain the
locationId
. - Request the
/locations/{locationId}/rooms
endpoint to retrieve the list of rooms. - Map desired rooms using provided Room endpoints.
- Leverage Device APIs to assign their
deviceId
to thelocationId
androomId
.
Create a Room
Creating a Room in SmartThings only requires a name
:
- Request
POST /locations/{locationId}/rooms
Get Devices in a Room
List devices in a room using a combination of locationId
and roomId
:
- Request
GET /locations/{locationId}/rooms/{roomId}/devices
Add/Move Devices to a Room
Add devices to an existing room belonging to the location. This will move a Device if it is already in another room.
Delete Devices from a Room
Remove one or more Devices from a Room. This will not remove them from the Location.
- Request
DELETE /locations/{locationId}/rooms/{roomId}/devices