Update site group

PUT /api/configuration/site-groups/{all}

Products: Operator (FOH)
Features: Front of House Generic Access (FOHGENERIC)

Overview

Updates a site group — a named collection of sites used to scope products, pricing and reporting across more than one centre.

This is a full replacement, not a partial update. description and eftCollection are written on every call, so omitting description clears the existing text and omitting eftCollection sets it to false. sites replaces the group's entire membership: every existing site link is deleted and rebuilt from the array you send, so [] empties the group.

sites cannot be omitted. Leaving the field out returns 500 rather than a helpful 400. Always send the full list, even when you are only changing the description.

Read the group first with Get site group by ID and send its description, eftCollection and complete site list back with your change applied. A successful update returns 204 No Content.

Endpoint

PUT {base_url}/api/configuration/site-groups/{all}

{base_url} is the environment URL issued to your integration. See Authenticating with Gladstone APIs.

Path parameters

Name	Type	Required	Description
`siteGroupId`	string	Yes	The site group's identifier, as returned in `id` by List site groups. Up to 15 characters. Before the lookup the value is converted to upper case and all spaces are removed, so `stgp 01` and `STGP01` reach the same group. An identifier that matches nothing fails with `404`.

Request body

Field	Type	Required	Description
`description`	string	No	The site group's display name — what staff and reports call this collection of sites. Maximum 255 characters (`The description cannot be more than 255 characters`), and an empty string is rejected with `The description cannot be null or empty`. It is written on every call, so omitting it or sending null wipes the stored description; resend the current value if you are not changing it.
`eftCollection`	boolean	No	Whether this group is an EFT collection group — used when direct debit collections are grouped across the group's sites rather than handled per site. Omitting it or sending null sets it to `false`, silently turning the flag off; send the value you want on every call.
`sites`	array of string	Yes	The complete list of site ids belonging to the group, as returned in `id` by List sites. The list is absolute, not additive: existing membership is cleared and rebuilt from what you send, so `[]` empties the group and a list omitting a site removes it. Every id must exist and each must appear only once — an unknown id, or the same id twice, fails with `One or more sites are not valid`, which does not say which entry was at fault. Matching ignores case. Although it is not marked as required, omitting the field causes a `500`, so treat it as required.

Sample request

cURL

curl -X PUT '{base_url}/api/configuration/site-groups/{all}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "string",
  "eftCollection": true,
  "sites": [
    "string"
  ]
}'

Errors

Status	Meaning	When
`400`	Bad request	`description` is longer than 255 characters or is an empty string. The body is a validation error object keyed by field name, carrying `The description cannot be more than 255 characters` or `The description cannot be null or empty`.
`400`	Bad request	An entry in `sites` does not match an existing site, or the same site id appears more than once — `One or more sites are not valid`. The message does not identify which entry failed. Nothing is written.
`404`	Not found	No site group has that `siteGroupId` after conversion to upper case and removal of spaces — `SiteGroupId: {siteGroupId} cannot be found`.
`500`	Internal server error	`sites` was omitted or sent as null. Also covers any other unexpected server-side failure.

This page as markdown · All pages · llms.txt