# Updates an existing organization's configuration and settings

`PUT /api/configuration/organisations/{all}`

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

HTML version: [Updates an existing organization's configuration and settings](https://support.gladstonesoftware.cloud/reference/configuration/updates-an-existing-organizations-configuration-and-settings)

## Overview

Updates an organisation — a partner or operator entity that sites are grouped under for branding, contact details and commercial reporting.

**Text fields merge; two fields do not.** Every string field is written only when you send a non-null value, so omitting one leaves it alone. The exceptions are the two that will catch you out:

- **`sites` replaces the organisation's whole site list, and omitting it empties it.** Existing site links are deleted on every call and only rebuilt from the array you send, so leaving `sites` out — or sending `[]` — detaches every site from the organisation.
- **`isActive` is applied on every call, so omitting it deactivates the organisation.** Sending null has the same effect.

**`type` is effectively required.** It is validated before anything else, and omitting it or sending null returns `500` rather than a helpful `400`.

Read the current state with [Get organisation by ID](retrieves-a-specific-organization-by-its-unique-identifier.md) and send the whole object back with your change applied. The update is all-or-nothing, so a failure applies nothing — including the site deletions.

**Almost every failure is a `400`, including a missing organisation and a failure to save.** There is no `404` on this endpoint, and a failure to save the update is reported as `400` with the generic message `Unable to update organisation` rather than a `500`. Do not treat `400` here as proof that your request was malformed. A successful update returns `204 No Content`.

## Endpoint

`PUT {base_url}/api/configuration/organisations/{all}`

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

## Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `organisationId` | integer (int32) | Yes | The organisation's identifier, as returned in `[].id` by [List organisations](retrieves-all-organizations-configured-in-the-system.md). Must be non-zero — `0` fails with `Organisation ID must be specified` — and must exist, or the call fails with `400` and `Organisation ID {id} cannot be found`. |

## Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | integer (int32) | No | Ignored. The `organisationId` from the URL is always used instead, so whatever you send here has no effect and cannot re-target the update. Omit it. |
| `type` | string | Yes | What kind of organisation this is: `partner` or `operator`. Matched case-insensitively, but **stored exactly as you send it**, so `Partner` and `partner` both validate and both persist verbatim — send lower case for consistency. An unrecognised value fails with `Invalid type specified, must be one of partner, operator`. Although marked optional, omitting it or sending null returns `500`, so always send it — resend the stored value when changing something else. |
| `name` | string | No | The organisation's trading name, as shown wherever it is displayed. Maximum 255 characters, and an empty string is rejected with `Name cannot be empty`. Omitting it or sending null leaves the stored name unchanged. |
| `legalName` | string | No | The registered legal entity name, which may differ from `name` and is what appears on invoices and contracts. Maximum 255 characters; an empty string is rejected with `Legal name cannot be empty`. Omitting it or sending null leaves the stored value unchanged. |
| `description` | string | No | Free-text description of the organisation. Maximum 255 characters; an empty string is rejected with `Description cannot be empty`, so there is no way to clear it once set. Omitting it or sending null leaves the stored value unchanged. |
| `websiteUrl` | string | No | The organisation's public website address. Maximum 255 characters. Stored as free text — nothing validates that it is a well-formed URL or reachable. Omitting it or sending null leaves the stored value unchanged. |
| `logoUrl` | string | No | Address of the organisation's logo image. Maximum 255 characters, stored as free text with no format checking. Upload the image first with [Upload an image to public storage](uploads-an-image-to-public-storage-blob-not-member-dependent-or-anything.md) and put the returned URL here. Omitting it or sending null leaves the stored value unchanged. |
| `address` | object | No | The organisation's postal address. Every field inside is individually optional and merges, so send only the lines you are changing. Omitting the object entirely is safe, but sending it explicitly as `null` returns `500` — send `{}` if you want to say "no address change" verbosely. |
| `address.addressLine1` | string | No | First line of the address. Maximum 100 characters. Omitting it or sending null leaves the stored value unchanged. |
| `address.addressLine2` | string | No | Second line of the address. Maximum 100 characters. Omitting it or sending null leaves the stored value unchanged. |
| `address.addressLine3` | string | No | Third line of the address. Maximum 100 characters. Omitting it or sending null leaves the stored value unchanged. |
| `address.town` | string | No | Town or city. Maximum 100 characters. Note the name differs between request and response shapes elsewhere in the API, where the same value appears as `townCity`. |
| `address.region` | string | No | County, state or region. Maximum 100 characters. Omitting it or sending null leaves the stored value unchanged. |
| `address.postCode` | string | No | Postal or ZIP code. Maximum 25 characters. Not validated against any postcode format, so send it in whatever form your country uses. |
| `address.country` | string | No | Country, as free text rather than an ISO code — nothing constrains the value. Maximum 100 characters. |
| `contact` | object | No | The organisation's contact details. Both fields inside are optional and merge. As with `address`, omitting the object is safe but sending it explicitly as `null` returns `500`. |
| `contact.telephone` | string | No | Contact telephone number, as free text — no format or country-code validation. Maximum 100 characters. |
| `contact.email` | string | No | Contact email address. Maximum 255 characters. |
| `vatId` | string | No | The organisation's VAT registration number, for invoicing. Maximum 50 characters, stored as free text with no country-format checking. Omitting it or sending null leaves the stored value unchanged. |
| `isActive` | boolean | No | Whether the organisation is in use. **Applied on every call regardless: omitting it or sending null sets it to `false`** and deactivates the organisation even if you were only changing an address. Always send the value you want. |
| `sites` | array of string | No | The complete list of site ids belonging to this organisation, as returned in `id` by [List sites](get-all-sites-with-optional-filtering.md). **Existing links are deleted on every call and rebuilt only from what you send**, so omitting the field or sending `[]` detaches every site. Site ids are not checked up front, so an unknown id makes the save fail and comes back as `400` with the generic `Unable to update organisation`. |

## Sample request

```bash title="cURL"
curl -X PUT '{base_url}/api/configuration/organisations/{all}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "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 |
|--------|---------|------|
| `400` | Bad request | `organisationId` is `0` — `Organisation ID must be specified`. |
| `400` | Bad request | `type` is not `partner` or `operator` — `Invalid type specified, must be one of partner, operator`. |
| `400` | Bad request | No organisation has that `organisationId` — `Organisation ID {organisationId} cannot be found`. There is no `404` on this endpoint. |
| `400` | Bad request | A field exceeds its maximum length, or `name`, `legalName`, `description` or `type` is an empty string. Returned automatically as a validation problem document keyed by field. |
| `400` | Bad request | The update could not be saved — `Unable to update organisation`. The most likely cause is a `sites` entry that does not match a real site. Nothing is applied, so the site links are left as they were. |
| `500` | Internal server error | `type` was omitted or sent as null, or `address` or `contact` was sent explicitly as null. None of these is reported as a `400`. |