Device Groups

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.

# 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

The existing /geofences/:id endpoints remain fully functional for backward compatibility.

Admin only

All group operations require an admin API key.

Getting Started

Concepts

Overview

Creating a group

Assigning devices to a group

Config resolution

Example

Geofences

Admin only

​Overview

​Creating a group

​Assigning devices to a group

​Config resolution

​Example

​Geofences

​Admin only

Overview

Creating a group

Assigning devices to a group

Config resolution

Example

Geofences

Admin only