# Creates a status

`POST /api/configuration/statuses`

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

HTML version: [Creates a status](https://support.gladstonesoftware.cloud/reference/configuration/creates-a-status)

## 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](../../guides/authenticating-with-gladstone-apis.md).

## 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

```bash title="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. |