Group List Request

The GroupListRequest retrieves the groups that are visible to your customer account. Groups are named containers used across FlexCloud to organise resources — for example, they can be assigned to devices (DeviceListRequest) or to power schedule sets (PowerScheduleSetListRequest) — and they are filtered on and referenced by id in many other requests.

Typical use cases:

• Discovering the groups your authentication has access to before you filter other list requests by groups.
• Rendering a name for a group id you already have (using detailTypes: [1] (NAMES) to include human-readable names).
• Inspecting the resourceTypeId associated with each group to understand what kind of resources the group can contain.

Preparations

• Launch the development client as described in the FlexConnect API — First Steps.
• Navigate to http://localhost:8080/ui.
• Select the documentation for Group List Request in the left pane.

Request

Run the GroupListRequest using the JSON body below.

1. Run the request on app/v1/GroupListRequest.
2. Set pagination.limit to the number of groups you want returned per page.
3. Set detailTypes to control which optional lists (nested groups, tags, attributes, permissions) and names are included in the response.
4. Optionally, add a filter to narrow the result set by group ids, resource-type ids, nested groups, tags, or attributes.

Request body

{
  "header": {
    "reqId": 1234,
    "timeoutMs": 10000
  },
  "pagination": {
    "limit": 100
  },
  "detailTypes": [1, 2, 3, 4, 5]
}

The example above requests all detail types, so each group in the response carries its groups, tags, attributes, and permissions lists with names populated. Detail types are additive — request only the ones you need.

Request fields

Field	Description
header.reqId	Client-defined identifier for the request. The same value is returned in the response header to correlate requests and responses.
header.timeoutMs	Maximum time (in milliseconds) the platform waits for the result before responding with a timeout error.
pagination.limit	Maximum number of groups returned in a single response.
pagination.cursorValue	Cursor value returned in a previous response as cursorNext or cursorPrevious. Use it to iterate through large result sets.
filter.groupIds	If non-empty, only groups with these ids are returned.
filter.resourceTypeIds	If non-empty, only groups associated with these resource types are returned.
filter.groups	If non-empty, only groups that themselves belong to at least one of these parent groups are returned.
filter.tags	If non-empty, only groups tagged with at least one of these tags are returned.
filter.attributes	If non-empty, only groups with matching attribute id and value are returned.
detailTypes	List of optional detail types to include in the response. See detailTypes values.

detailTypes values

Value	Code	Description
1	NAMES	Include the human-readable names of nested groups, tags, and attributes in the response (otherwise only their ids are returned).
2	GROUPS	Include the groups list for each group (the parent groups it belongs to).
3	TAGS	Include the tags list for each group.
4	ATTRIBUTES	Include the attributes list for each group.
5	PERMISSIONS	Include the permissions list for each group.

Request only what you need Detail types are additive — request the union of what you actually need. The id, resourceTypeId, name, and description of each group are always returned; the groups, tags, attributes, and permissions lists are only included when their corresponding detail type is requested. Add NAMES (1) whenever you need to render labels for nested groups, tags, or attributes rather than just their ids. :::

Filtering example

To list only the groups whose name has been resolved (via detailTypes: [1]), that belong to a specific parent group, and that carry a specific attribute value, use:

{
  "header": {
    "reqId": 1234,
    "timeoutMs": 10000
  },
  "pagination": {
    "limit": 100
  },
  "filter": {
    "groupIds": [1],
    "resourceTypeIds": [1],
    "groups": [{ "id": 1 }],
    "tags": [],
    "attributes": [{ "id": 1, "value": "2026-01-01" }]
  },
  "detailTypes": [1]
}

Response

Response body

{
  "header": {
    "reqId": 1234
  },
  "pagination": {
    "cursorNext": "1wsf="
  },
  "groups": [
    {
      "id": 1,
      "resourceTypeId": 1,
      "name": "Group 1",
      "description": "Group 1 description",
      "groups": [{ "id": 1, "name": "FHE internal groups" }],
      "tags": [],
      "attributes": [],
      "permissions": [{ "permissionTypeId": 1, "permissionCodeId": 1 }]
    }
  ]
}

Response fields

Field	Description
groups[].id	Identifier of the group. Use this value as id when referencing the group from other requests (for example, in filter.groups of another list).
groups[].resourceTypeId	Identifier of the resource type the group is associated with. Determines what kind of resources may be members of the group.
groups[].name	Human-readable name of the group.
groups[].description	Description of the group.
groups[].groups	List of parent groups the group itself belongs to. Included when detailTypes contains 2 (GROUPS). Names are only returned when detailTypes also includes 1 (NAMES).
groups[].tags	Tags associated with the group. Included when detailTypes contains 3 (TAGS). Names are only returned when detailTypes also includes 1 (NAMES).
groups[].attributes	Additional key/value metadata attached to the group. Included when detailTypes contains 4 (ATTRIBUTES). Names are only returned when detailTypes also includes 1 (NAMES).
groups[].permissions	Permissions your authentication has on this group. Included when detailTypes contains 5 (PERMISSIONS).
pagination.cursorNext / cursorPrevious	Returned when the result set is larger than limit. Pass either value as pagination.cursorValue in a follow-up request to paginate.

Resolve names in one call Include 1 (NAMES) in detailTypes when you need to display parent-group, tag, or attribute labels in a UI — otherwise the response only carries their ids and you would have to look each one up separately. :::

Pagination

When the number of matching groups exceeds pagination.limit, the response includes a pagination.cursorNext value (and a cursorPrevious value when iterating). Pass either value as pagination.cursorValue in a follow-up request — keeping filter and detailTypes unchanged — to retrieve the next or previous page. Iteration ends when no further cursor is returned.