Creates a new organization in the system

POST /api/configuration/organisations

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

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.

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

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.

This page as markdown · All pages · llms.txt