# Retrieves all organizations configured in the system

`GET /api/configuration/organisations`

- **Success:** `200 OK`
- **Products:** Operator (`FOH`)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [Retrieves all organizations configured in the system](https://support.gladstonesoftware.cloud/reference/configuration/retrieves-all-organizations-configured-in-the-system)

## Overview

Returns every organisation configured for your tenant. An organisation is the legal or commercial
entity that sits above sites — the operator that runs the centres, or a partner working with them —
and carries the name, registered address, VAT identifier and logo that appear on customer-facing
documents such as invoices.

Each organisation lists the sites mapped to it, so this call is the way to work out which trading
entity a site belongs to.

The full set is returned every time: no paging, no filtering, and inactive organisations are
included alongside active ones — check `isActive` rather than assuming the list is current. To read
one organisation you already have the id for, use
[Retrieve an organisation](retrieves-a-specific-organization-by-its-unique-identifier.md).

## Endpoint

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

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

## Sample request

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

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `[].id` | integer (int32) | The organisation's identifier, and the value to pass to [Retrieve an organisation](retrieves-a-specific-organization-by-its-unique-identifier.md). |
| `[].type` | string | What kind of entity this is: `operator` for the business running the centres, or `partner` for an associated organisation. Those are the only two values accepted when an organisation is created or updated, compared case-insensitively. |
| `[].name` | string | The organisation's trading name, as displayed. Maximum 255 characters. Not necessarily the registered name — see `legalName`. |
| `[].legalName` | string | The registered legal name of the entity, for use where a document must name the company rather than the brand. Maximum 255 characters. May be `null` where only a trading name was recorded. |
| `[].description` | string | Free-text notes about the organisation, maximum 255 characters. `null` when none was entered. |
| `[].websiteUrl` | string | The organisation's public website address, maximum 255 characters. Returned as entered — it is not validated as a well-formed URL, so treat it as untrusted text before rendering it as a link. |
| `[].logoUrl` | string | Address of the organisation's logo image, maximum 255 characters. Not validated as a URL and not hosted by this endpoint. `null` when no logo was set. |
| `[].address` | object | The organisation's registered or trading address. Always present as an object, but every field inside it is individually optional, so expect an object of nulls rather than a missing address. |
| `[].address.addressLine1` | string | First line of the address, maximum 100 characters. |
| `[].address.addressLine2` | string | Second line of the address, maximum 100 characters. `null` when unused — the lines are not compacted, so do not assume line 2 is filled before line 3. |
| `[].address.addressLine3` | string | Third line of the address, maximum 100 characters. Often `null`. |
| `[].address.town` | string | Town or city, maximum 100 characters. |
| `[].address.region` | string | County, state or region, maximum 100 characters. |
| `[].address.postCode` | string | Postal code, maximum 25 characters — the shortest of the address fields, and the one most likely to reject an overseas value on write. Returned as entered, with no formatting or validation applied. |
| `[].address.country` | string | Country as free text, maximum 100 characters — not an ISO country code, and not validated against a list. |
| `[].contact` | object | The organisation's general contact details. Always present as an object, with both fields individually optional. |
| `[].contact.telephone` | string | Contact telephone number as free text, maximum 100 characters. No format is enforced, so expect spacing and country codes to vary. |
| `[].contact.email` | string | Contact email address, maximum 255 characters. Only the length is checked — the address is not validated, so it may not be deliverable or even well-formed. |
| `[].vatId` | string | The organisation's VAT registration identifier, maximum 50 characters, returned as entered with no format check. `null` for organisations that are not VAT registered or where it was not recorded. |
| `[].isActive` | boolean | Whether the organisation is in use. `false` means retired rather than unknown. Inactive organisations are still returned by this endpoint and still keep their site mappings — filter on this field yourself. |
| `[].sites` | array of string | The site codes mapped to this organisation, which is how you tell which trading entity a site belongs to. Empty rather than `null` when no sites are mapped. The mapping is maintained on the organisation, so a site appearing under two organisations is a configuration error rather than something to handle. |

## Sample response

```json title="200 OK"
[
  {
    "id": 12345,
    "type": "string",
    "name": "string",
    "legalName": "string",
    "description": "string",
    "websiteUrl": "string",
    "logoUrl": "string",
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "addressLine3": "string",
      "town": "string",
      "region": "string",
      "postCode": "string",
      "country": "string"
    },
    "contact": {
      "telephone": "string",
      "email": "member@example.com"
    },
    "vatId": "string",
    "isActive": true,
    "sites": [
      "string"
    ]
  }
]
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `500` | Internal server error | An unexpected server-side failure while reading the organisations. The body is a generic platform error rather than a message specific to this endpoint. |