# Get all sites with optional filtering

`GET /api/configuration/sites`

- **Success:** `200 OK`
- **Products:** Operator (`FOH`), Consumer (`CONSUMER`), Integrations (`INTEGRATIONS`) (any one of these products, not all)
- **Features:** Online Bookings (`ONLINEBOOK`), Online Joining (`ONLINEJOIN`), DataHub (4Global) Integration (`DATAHUB`), TRP Integration (`TRP`), Front of House Generic Access (`FOHGENERIC`) (any one of these features, not all)

HTML version: [Get all sites with optional filtering](https://support.gladstonesoftware.cloud/reference/configuration/get-all-sites-with-optional-filtering)

## Overview

Lists the sites — the physical leisure centres, pools and venues — configured in one tenant. Almost every other Configuration and Booking call is scoped by a site id, so this is normally the first call an integration makes: it is how you discover the `id` values everything else expects.

Site ids are operator-defined strings of up to 15 characters, assigned when the site was created. They are meaningful only inside one tenant, carry no cross-tenant meaning, and are not GUIDs — treat them as opaque, store what this endpoint returns, and never hardcode them.

**Two query parameters change the shape of the response, not just its contents.** With `includeFacilitiesAndAmenities` omitted or `false` you get the body documented below. With it set to `true` you get a different object: the same fields **plus** `amenities` and `facilities` arrays, each element carrying `id`, a stable key (`amenityKey` / `facilityKey`), `name`, `description` and `translations`. Make your parser tolerate the extra members.

**The `organisations`, `images` and `socialMedia` arrays are always `null` unless you ask for facilities and amenities.** The default response never populates them. If you need a site's logo gallery, social links or owning organisations, you must call with `includeFacilitiesAndAmenities=true`, which does populate them.

When nothing matches, the response is `200` with an empty array `[]`. This endpoint does not return `204`. There is likewise no `404` here; the only `404` in this area comes from [Get site by ID](get-site-by-id.md).

Inactive sites are included by default. Each site's state is returned as `isActive`; with no `isActive` parameter the response contains active and inactive sites together. Filter explicitly if you only want live venues — a consumer-facing integration almost certainly wants `isActive=true&isWebVisible` checked as well, since the two flags are independent and `isWebVisible` is not filterable here.

All three parameters filter the same snapshot of the site list, and a site changed outside the API may not appear until that snapshot is refreshed. The `includeFacilitiesAndAmenities=true` variant is refreshed separately, so the two views can briefly disagree.

## Endpoint

`GET {base_url}/api/configuration/sites`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `isActive` | boolean | No | Filters on the site's active state: a site is active unless it has been explicitly marked inactive. Pass `true` for live sites, `false` for retired ones. Omit it and both are returned — this is the default and is the single easiest way to accidentally offer a closed centre to a customer. |
| `includeFacilitiesAndAmenities` | boolean | No | Changes the response object, not just its contents. Only the exact value `true` takes effect; `false` and omission both give the standard body. With `true` you additionally get `amenities` and `facilities` arrays, and the `organisations`, `images` and `socialMedia` arrays are populated instead of being null. It is a heavier request, so use it only when you need those arrays. |
| `siteGroupId` | string | No | Restricts the result to sites that belong to one site group — an operator-defined grouping of sites, listed by [Retrieve all site groups](retrieves-all-site-groups-with-their-configuration-details.md). Pass the group's `id`, not its description. Unlike the other two parameters this one is validated first: an id that matches no site group is rejected with `400` rather than returning an empty array. Once validated, the membership match is case-insensitive. A valid group with no sites in it returns `200` and `[]`. |

## Sample request

```bash title="cURL"
curl -X GET '{base_url}/api/configuration/sites' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'
```

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `[].id` | string | The site's identifier, and the value to send wherever an endpoint takes a `{siteId}`. Operator-defined, up to 15 characters, unique within the tenant and meaningless outside it. Treat it as opaque and do not assume a numeric or GUID form. |
| `[].name` | string | The site's display name — what a member would recognise the centre by. Up to 255 characters and never blank; writes reject an empty name. |
| `[].legalName` | string | The registered legal entity that operates the site, where it differs from `name` — used on invoices and formal documents. Up to 255 characters, and null when the operator has not set one. |
| `[].vatId` | string | The site's VAT registration number as free text, up to 20 characters. No format or checksum is enforced, so validate it yourself before putting it on a document. Null when unset. |
| `[].description` | string | Long-form descriptive copy about the site, suitable for a centre page. Unbounded in length, but the create and update endpoints cap what you can write at 255 characters, so older records can be longer than you can round-trip. Null when unset. |
| `[].address` | object | The site's postal address. The object itself is always present in the response, even when every member inside it is null. |
| `[].address.addressLine1` | string | First line of the site's street address, up to 100 characters. Null when unset — the address is not mandatory, so do not assume line 1 is populated before line 2. |
| `[].address.addressLine2` | string | Second line of the street address, up to 100 characters. Null when unset. |
| `[].address.addressLine3` | string | Third line of the street address, up to 100 characters. Null when unset. |
| `[].address.townCity` | string | Town or city, up to 100 characters. Null when unset. |
| `[].address.region` | string | County, state or region, up to 100 characters. Free text with no controlled vocabulary, so values are inconsistent between operators. Null when unset. |
| `[].address.postalCode` | string | Postcode or ZIP code, up to 25 characters. Returned exactly as the operator typed it — neither normalised nor validated against any country's format. Null when unset. |
| `[].address.country` | string | Country name as free text, up to 100 characters. Not an ISO country code and not validated, so do not key logic off it. Null when unset. |
| `[].location` | object | The site's map coordinates. The object is always present even when both members are null. |
| `[].location.latitude` | string | Latitude of the site, returned as a **string** of up to 40 characters rather than a number, with no format enforced — parse defensively and expect decimal degrees. Null when the operator has not geocoded the site, which is common, so any map feature needs a fallback. |
| `[].location.longitude` | string | Longitude of the site, returned as a **string** of up to 40 characters rather than a number, with no format enforced. Null whenever `latitude` is null; treat the pair as all-or-nothing. |
| `[].contact` | object | Public contact details for the site. The object is always present even when both members are null. |
| `[].contact.telephone` | string | Public telephone number for the site, up to 100 characters. Free text — no country code is added and no format is enforced, so it may or may not be dialable as given. Null when unset. |
| `[].contact.email` | string | Public enquiry email address for the site, up to 255 characters. Not validated as an address on read. Null when unset. |
| `[].websiteUrl` | string | The site's own web page, up to 255 characters. Free-form: no scheme is added and no validation is applied, so treat it as an untrusted string. Null when unset. |
| `[].logoUrl` | string | URL of the site's logo image, up to 255 characters. Not validated. Null when unset. This is a single logo; the `images` gallery is separate and only returned with `includeFacilitiesAndAmenities=true`. |
| `[].termsConditionsUrl` | string | URL of the terms and conditions a member accepts when transacting with this site, up to 255 characters. Null when unset — do not assume a site has one. |
| `[].privacyPolicyUrl` | string | URL of the site's privacy policy, up to 255 characters. Null when unset. |
| `[].openActiveTaxMode` | string | The tax treatment the site declares when its data is published to OpenActive, the open data standard for physical activity opportunities. Free text of up to 100 characters, unvalidated. |
| `[].isActive` | boolean | Whether the site is in service. `true` unless the site has been explicitly marked inactive, so a site whose inactive flag has never been set reports `true`. Both active and inactive sites are returned unless you pass `isActive`. |
| `[].isWebVisible` | boolean | Whether the operator has chosen to expose this site on consumer-facing web channels. Defaults to off; an unset value is reported here as `false`, never as null. Independent of `isActive` — a site can be active but not web-visible, and there is no query parameter to filter on it, so filter client-side. |
| `[].openingDate` | string (date-time) | The site's opening date. The time-of-day is truncated to midnight, so only the date part carries meaning even though the value is formatted as a date-time. Null when the operator has not recorded one. |
| `[].organisations` | array of object | The organisations associated with the site. **Always null unless you call with `includeFacilitiesAndAmenities=true`** — the default response does not include them. When populated, entries are not filtered on the organisation's own inactive flag, so a retired organisation still appears. |
| `[].organisations[].id` | integer (int32) | The organisation's identifier, a tenant-local integer allocated in sequence. Not stable across tenants or environments. |
| `[].organisations[].type` | string | The organisation's role, always exactly `operator` or `partner`. Lower case in both cases. `operator` is the body that runs the site; `partner` is an associated organisation. |
| `[].organisations[].name` | string | The organisation's trading name, up to 255 characters. Always set. |
| `[].images` | array of object | The site's image gallery. **Always null unless you call with `includeFacilitiesAndAmenities=true`.** Returns an empty array rather than null when that flag is set and the site has no images. |
| `[].images[].id` | integer (int32) | The image record's identifier, a tenant-local integer allocated in sequence. Also the key its `translations` belong to. |
| `[].images[].url` | string | Where the image is hosted, up to 2000 characters. Always set. |
| `[].images[].description` | string | Caption or alt text for the image, up to 255 characters. Null when the operator did not supply one, so do not rely on it for accessible alt text without a fallback. |
| `[].images[].translations` | array of object | Localised versions of this image's text, one entry per property per culture. Empty array when none exist. |
| `[].images[].translations[].type` | string | The name of the property being translated, not a translation category. Up to 50 characters. |
| `[].images[].translations[].culture` | string | The culture the text is written for, as a code from the tenant's culture list — see [Get all available cultures](get-all-available-cultures.md). Up to 20 characters. |
| `[].images[].translations[].text` | string | The translated value for that property in that culture, replacing the untranslated field of the same name. |
| `[].socialMedia` | array of object | The site's social media links. **Always null unless you call with `includeFacilitiesAndAmenities=true`.** Returns an empty array rather than null when that flag is set and the site has no links. |
| `[].socialMedia[].id` | integer (int32) | The link record's identifier, a tenant-local integer allocated in sequence. Also the key its `translations` belong to. |
| `[].socialMedia[].url` | string | The social media profile or page address, up to 2000 characters. Always set. |
| `[].socialMedia[].description` | string | Label for the link, up to 255 characters. Null when unset. There is no separate machine-readable field naming the network, so this is the only clue to which platform the link points at. |
| `[].socialMedia[].logoUrl` | string | Icon to show alongside the link, up to 2000 characters. Null when unset. |
| `[].socialMedia[].translations` | array of object | Localised versions of this link's text, one entry per property per culture. Empty array when none exist. |
| `[].socialMedia[].translations[].type` | string | The name of the property being translated, not a translation category. Up to 50 characters. |
| `[].socialMedia[].translations[].culture` | string | The culture the text is written for, as a code from the tenant's culture list — see [Get all available cultures](get-all-available-cultures.md). Up to 20 characters. |
| `[].socialMedia[].translations[].text` | string | The translated value for that property in that culture. |
| `[].translations` | array of object | Localised text for the site itself, one entry per translated property per culture. Unlike the three arrays above this is populated on both variants of the call, and is an empty array — never null — when the site has no translations. Apply an entry by overwriting the top-level field its `type` names. |
| `[].translations[].type` | string | The name of the site property this entry translates, for example the field behind `name` or `description`. The name is misleading: it holds the property name, not the object type, and is up to 50 characters. Match it against the field you intend to localise rather than assuming a fixed set. |
| `[].translations[].culture` | string | The culture this text belongs to, as a code from the tenant's culture list — see [Get all available cultures](get-all-available-cultures.md). Up to 20 characters, and always a culture that actually exists. |
| `[].translations[].text` | string | The translated value. Unbounded in length for site translations. |

## Sample response

```json title="200 OK"
[
  {
    "id": "string",
    "name": "string",
    "legalName": "string",
    "vatId": "string",
    "description": "string",
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "addressLine3": "string",
      "townCity": "string",
      "region": "string",
      "postalCode": "string",
      "country": "string"
    },
    "location": {
      "latitude": "string",
      "longitude": "string"
    },
    "contact": {
      "telephone": "string",
      "email": "member@example.com"
    },
    "websiteUrl": "string",
    "logoUrl": "string",
    "termsConditionsUrl": "string",
    "privacyPolicyUrl": "string",
    "openActiveTaxMode": "string",
    "isActive": true,
    "isWebVisible": true,
    "openingDate": "2026-08-14T19:00:00Z",
    "organisations": [
      {
        "id": 12345,
        "type": "string",
        "name": "string"
      }
    ],
    "images": [
      {
        "id": 12345,
        "url": "string",
        "description": "string",
        "translations": [
          {
            "type": "string",
            "culture": "string",
            "text": "string"
          }
        ]
      }
    ],
    "socialMedia": [
      {
        "id": 12345,
        "url": "string",
        "description": "string",
        "logoUrl": "string",
        "translations": [
          {
            "type": "string",
            "culture": "string",
            "text": "string"
          }
        ]
      }
    ],
    "translations": [
      {
        "type": "string",
        "culture": "string",
        "text": "string"
      }
    ]
  }
]
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | Two distinct causes. Most often you passed a `siteGroupId` that matches no site group in this tenant, in which case the body is the plain string `Could not find the site group id {siteGroupId}`. Separately, a value for `isActive` or `includeFacilitiesAndAmenities` that does not parse as a boolean is rejected, and the body is then a validation problem document (`application/problem+json`), not a plain string — so parse the body defensively. |
| `500` | Internal server error | Any unexpected server-side failure while loading or filtering the site list. The body is empty and carries no detail. Retrying is reasonable, since the failure is often transient. |