Creates a status

POST /api/configuration/statuses

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

Overview

Defines a member status — the label a member's record carries to say where they stand, such as active, suspended or lapsed. A status is a definition only; assigning one to a member is done through the member endpoints, which take the status's id.

The four boolean flags are the point of the call. They are not descriptive: they change how the billing and membership engines treat every member holding the status, so decide them before you create it rather than after members are attached.

A successful call returns 201 Created with an empty body and no Location header — including when the platform generated the id for you. If you did not supply an id you will not be told what it is; call GET /api/configuration/statuses and match on description to find it. Supplying your own id is the only way to know it up front.

The one trap worth knowing before you start: description passes validation up to 255 characters but only 25 can be stored, so anything longer passes validation and then fails with a 500. Keep descriptions to 25 characters.

Endpoint

POST {base_url}/api/configuration/statuses

{base_url} is the environment URL issued to your integration. See Authenticating with Gladstone APIs.

Request body

Field	Type	Required	Description
`id`	string	No	The code you will quote whenever you set this status on a member, unique within your tenant. Maximum 15 characters (`The status ID cannot be more than 15 characters`). It is upper-cased and has every space stripped, so `my status` is stored and must later be quoted as `MYSTATUS`. It must not match an existing status; a clash is rejected with `409` and `The status ID {id} already exists`. Omit it, or send an empty string, and the platform generates one for you in the form `STUS` followed by eleven digits (`STUS00000000001`), numbered from the highest existing `STUS…` id — but the response does not tell you what it chose.
`description`	string	Yes	The status's human-readable label. It must not be empty (`The description must not be empty`). Request validation allows 255 characters but only 25 can be stored, so anything between 26 and 255 characters passes validation and then fails with a `500`. Treat 25 characters as the real maximum.
`backColourHex`	string	No	The background colour used when the status is shown in Gladstone's own interfaces, given as a `#RRGGBB` hex string. Omit it, send null or send an empty string and it defaults to `#E0E0E0`. A string that cannot be parsed as a colour fails the whole request with `500` rather than a validation error.
`textColourHex`	string	No	The foreground colour for the status label, given as a `#RRGGBB` hex string, parsed the same way as `backColourHex`. Omit it, send null or send an empty string and it defaults to `#000000`.
`collectSalesInvoices`	boolean	No	Whether sales invoices continue to be collected from members holding this status. Omit it, or send null, and it is stored as `false`.
`treatMembersAsExpired`	boolean	No	Whether members holding this status are treated as expired by the rest of the platform. Omit it, or send null, and it is stored as `false`.
`freezeSubscriptions`	boolean	No	Whether subscription billing is frozen for members holding this status. Omit it, or send null, and it is stored as `false`.
`prospectStatus`	boolean	No	Whether this status marks a prospect rather than a joined member. Omit it, or send null, and it is stored as `false`.

Sample request

cURL

curl -X POST '{base_url}/api/configuration/statuses' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "string",
  "description": "string",
  "backColourHex": "string",
  "textColourHex": "string",
  "collectSalesInvoices": true,
  "treatMembersAsExpired": true,
  "freezeSubscriptions": true,
  "prospectStatus": true
}'

Errors

Status	Meaning	When
`400`	Bad request	`description` is missing or empty (`The description must not be empty`), longer than 255 characters (`The status description cannot be more than 255 characters`), or `id` is longer than 15 characters (`The status ID cannot be more than 15 characters`). The body is a validation error object keyed by field name.
`400`	Bad request	The body is not valid — for example one of the four boolean flags sent as a string rather than a boolean.
`409`	Conflict	The `id` you supplied is already in use — `The status ID {id} already exists`. Because the id is upper-cased and has spaces removed before checking, `active`, `ACTIVE` and `Act ive` all collide with an existing `ACTIVE`.
`409`	Conflict	The clash was detected when saving rather than by the check above — `This entry already exists in the database`. In practice this is the same id clash, racing against a concurrent create.
`500`	Internal server error	`description` is between 26 and 255 characters long. Request validation allows it, but only 25 characters can be stored. Nothing is created.
`500`	Internal server error	`backColourHex` or `textColourHex` could not be parsed as a colour. The failure is not reported as a validation error. Nothing is created.
`500`	Internal server error	The status could not be saved for any other reason. Nothing is created, and the request is safe to retry.

This page as markdown · All pages · llms.txt