# Creates a new organization in the system

`POST /api/configuration/organisations`

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

HTML version: [Creates a new organization in the system](https://support.gladstonesoftware.cloud/reference/configuration/creates-a-new-organization-in-the-system)

## Overview

Registers an organisation — a named legal entity of one of two kinds, `partner` or `operator` — and optionally maps it to the sites it covers. Organisations are reference data: they group sites under an owning body and carry that body's address, contact and VAT details.

**`type` has its own check, and it is validated before anything else.** It must be `partner` or `operator`; the comparison ignores case, so `Partner` and `PARTNER` both pass, but the value is stored exactly as you sent it. Normalise to lower case yourself if you want consistent data back from the retrieve endpoints.

A successful call answers `201 Created` **with an empty body**. The identifier is generated by the platform and is not returned to you, so to find it you have to list the organisations afterwards.

**Nothing enforces uniqueness.** There is no check on `name`, `legalName` or `vatId`, so retrying after a timeout creates a second organisation rather than failing. Retry only when you are prepared to reconcile duplicates.

The call is all-or-nothing, covering both the organisation and its site mappings, so a failure part-way through leaves nothing behind.

## Endpoint

`POST {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).

## Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | integer (int32) | No | Ignored on create. The identifier is generated by the platform; any value you send here is discarded. It is present only because create and update take the same body — see the update endpoint, where it identifies the organisation to change. |
| `type` | string | Yes | The kind of organisation, and the only value with its own allowed-value check. It must be `partner` or `operator`; anything else is rejected with `400` and the body `Invalid type specified, must be one of partner, operator`. The check is case-insensitive but storage is not, so `PARTNER` is accepted and stored as `PARTNER`. Maximum 20 characters. Omitting it, or sending null, is not handled as a validation failure — the request fails with `500` instead of `400`. |
| `name` | string | Yes | The organisation's working name, used wherever it is listed. Between 1 and 255 characters — an empty string returns `400` with `Name cannot be empty`, and more than 255 with `Name cannot be more than 255 characters`. Request validation does not flag it as missing, but the organisation cannot be saved without it, so omitting the field returns `400` with the body `Unable to create organisation`. Not checked for uniqueness. |
| `legalName` | string | Yes | The registered legal entity name, held separately from `name` so that a trading name and a registered name can differ. Between 1 and 255 characters, with the same `Legal name cannot be empty` / `Legal name cannot be more than 255 characters` messages. Like `name`, it cannot be left out: omitting it returns `400` with `Unable to create organisation`. |
| `description` | string | Yes | Free text describing the organisation. Between 1 and 255 characters. Despite reading like an optional note, it cannot be left out: omit it and the call fails with `400` and the body `Unable to create organisation`. Send a placeholder rather than leaving it out. |
| `websiteUrl` | string | No | The organisation's public website address, stored as given — no format check is applied. Maximum 255 characters. Omit it, or send null, to store nothing. |
| `logoUrl` | string | No | Location of the organisation's logo, for interfaces that display it. Stored verbatim with no fetch or format check. Maximum 255 characters. Omit it, or send null, to store nothing. |
| `address` | object | No | The organisation's postal address. The object is created empty by default, so you can leave it out entirely and every address field stays null. Do **not** send an explicit `null` for it: the call is rejected with `400` and the body `Unable to create organisation`. |
| `address.addressLine1` | string | No | First line of the postal address. Maximum 100 characters (`Address line 1 cannot be more than 100 characters`). Omit or send null to leave it unset. |
| `address.addressLine2` | string | No | Second address line. Maximum 100 characters. No relationship to `addressLine1` is enforced — you can populate line 2 without line 1. |
| `address.addressLine3` | string | No | Third address line. Maximum 100 characters. Optional and independent of the other lines. |
| `address.town` | string | No | Town or city. Maximum 100 characters. The retrieve endpoints return it as `address.town`. |
| `address.region` | string | No | County, state or region. Maximum 100 characters. Free text — there is no lookup list. |
| `address.postCode` | string | No | Postal or ZIP code. Maximum 25 characters, and the shortest field in the address, so long international codes are the first to be rejected. No format validation is applied. |
| `address.country` | string | No | Country name. Maximum 100 characters. Free text, not an ISO country code — nothing constrains it to a known list. |
| `contact` | object | No | General contact details for the organisation. Like `address`, it defaults to an empty object, so omitting it is safe but sending an explicit `null` is not: the call fails with `400` and the body `Unable to create organisation`. |
| `contact.telephone` | string | No | Contact telephone number, stored as text with no formatting or dialling-code rules. Maximum 100 characters. |
| `contact.email` | string | No | Contact email address. Maximum 255 characters. Length is the only check — the value is not validated as an email address, nor is anything sent to it. |
| `vatId` | string | No | The organisation's VAT registration number, for use on financial documents. Maximum 50 characters (`Vat ID cannot be more than 50 characters`). Free text, not validated against any VAT number format, and not checked for uniqueness. |
| `isActive` | boolean | No | Whether the organisation is in use. **Defaults to `true` when omitted**, which is the opposite of most create endpoints — send `false` explicitly to register an organisation that is not yet live. The retrieve endpoints return it as `isActive`. |
| `sites` | array of string | No | The identifiers of the sites this organisation covers, each mapped to the organisation. Each identifier must be at most 15 characters and must already exist as a site — an unknown identifier rejects the whole call with `400` and the body `Unable to create organisation`. The same site must not appear twice in the list, as a site can be mapped to a given organisation only once. Omit the field, or send an empty array or null, to create the organisation with no sites mapped. Note the update endpoint replaces the whole set, so always send the complete list there rather than just additions. |

## Sample request

```bash title="cURL"
curl -X POST '{base_url}/api/configuration/organisations' \
  -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 | `type` is present but is neither `partner` nor `operator`. The body is the plain string `Invalid type specified, must be one of partner, operator`. This check runs first, so a bad `type` masks every other problem in the request. |
| `400` | Bad request | A length or empty-string rule failed — for example `name` over 255 characters, `postCode` over 25, or `description` sent as `""`. The body is a validation error object keyed by field name, carrying messages such as `Name cannot be empty`. |
| `400` | Bad request | The organisation could not be saved, with the plain string `Unable to create organisation`. The usual causes are a missing `name`, `legalName` or `description`, a site identifier in `sites` that does not exist, the same site listed twice, or an explicit `null` sent for `address` or `contact`. Nothing is created. |
| `500` | Internal server error | `type` was omitted or sent as null. |