> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iotee.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Device Groups

> Group devices together to apply shared configuration and geofences.

## Overview

Device groups let you apply configuration and geofences to a set of devices without managing each device individually. Exchange owns group identity — you create a group via the API and store the returned `group_id` in your own system.

Groups are generic. Exchange has no opinion on what a group represents in your domain (a site, venue, fleet, etc.) — you define that mapping.

## Creating a group

Create a group via `POST /groups`. You can optionally provide your own numeric `group_id` — useful if you already have a numeric identifier (e.g. a site ID) that you want to use as the group ID. If you omit it, Exchange auto-generates one.

```bash theme={null}
# Let Exchange generate the ID
POST /groups
{ "name": "Site Alpha" }

# Provide your own ID (e.g. your existing site ID)
POST /groups
{ "name": "Site Alpha", "group_id": 42 }
```

Store the returned `group_id` on your side. This is the only identifier you need for all group operations.

## Assigning devices to a group

Devices have a single group assignment. Assign a device with `PUT /groups/{groupId}/devices/{hardwareId}`. Reassigning a device to a different group replaces the previous assignment.

## Config resolution

When a device connects or its config is requested, Exchange merges three layers in order of increasing specificity:

| Layer                  | Source                                         | Example                       |
| ---------------------- | ---------------------------------------------- | ----------------------------- |
| 1. Type defaults       | Device type definition                         | `{ realtime_enabled: false }` |
| 2. Group + type config | Set via `PUT /groups/{id}/config/{deviceType}` | `{ realtime_enabled: true }`  |
| 3. Per-device config   | Set via `PUT /devices/{id}/config`             | `{ realtime_enabled: false }` |

A value at layer 3 always wins over layer 2, which always wins over layer 1.

This means you can configure an entire group at once (layer 2), while individual devices can still override specific keys (layer 3).

### Example

```
Type default:   { realtime_enabled: false, key_keyless_state: "key" }
Group config:   { realtime_enabled: true }
Device config:  { key_keyless_state: "keyless" }

Resolved:       { realtime_enabled: true, key_keyless_state: "keyless" }
                          ^-- from group    ^-- from device
```

When you write a group config, Exchange immediately resolves and publishes the updated config to all devices of that type in the group. Retained MQTT messages ensure offline devices receive it on reconnect.

## Geofences

Groups share the same numeric ID space as the existing `/geofences/:id` endpoint. A group with `group_id: 42` stores its geofences at `device_group_id: 42` in the geofences collection — the same data accessible via the legacy endpoint.

Use `PUT /groups/{groupId}/geofences` to update geofences for a group. On success, Exchange publishes to all device types in the group:

* **Teebox:** retained MQTT message on `sit/{groupId}/sz`
* **Cartcaddie:** no MQTT push; devices fetch via `GET /geofences/{id}/download?token=xxx` when sent the `fetch_geofences` command

<Note>The existing `/geofences/:id` endpoints remain fully functional for backward compatibility.</Note>

## Admin only

All group operations require an admin API key.