Skip to main content

​
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:
LayerSourceExample
1. Type defaultsDevice type definition{ realtime_enabled: false }
2. Group + type configSet via PUT /groups/{id}/config/{deviceType}{ realtime_enabled: true }
3. Per-device configSet 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.