Skip to main content

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​

API Reference

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​

API Reference

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's region
{
    "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​

API Reference

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.

  1. For each residential unit, obtain the locationId.
  2. Request the /locations/{locationId}/rooms endpoint to retrieve the list of rooms.
  3. Map desired rooms using provided Room endpoints.
  4. Leverage Device APIs to assign their deviceId to the locationId and roomId.

Create a Room​

Creating a Room in SmartThings only requires a name:

POST /locations/{locationId}/rooms

Get Devices in a Room​

List devices in a room using a combination of locationId and roomId:

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.

DELETE /locations/{locationId}/rooms/{roomId}/devices