# Create a new title

`POST /api/configuration/titles`

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

HTML version: [Create a new title](https://support.gladstonesoftware.cloud/reference/configuration/create-a-new-title)

## Overview

Creates a title (Mr, Mrs, Dr etc) for use on member profile and registration forms. Titles are tenant-wide reference data, not per-site.

Each title is bound to exactly one gender, so a tenant that offers the same word for more than one gender needs a separate title for each — the pairing is what member forms filter on.

**A successful call returns `201` with an empty body.** The identifier is not returned. If you let the system generate the `id` for you by omitting it, the only way to discover the value is to list the titles afterwards and look for the new one. Supply your own `id` if you need to know it up front.

**The call is not idempotent in the useful sense.** Supplying an `id` that already exists returns `409` rather than overwriting, so a retry is safe. Omitting `id` is not safe to retry: each attempt generates a fresh `TITL…` identifier, so a retry after a timeout leaves you with two near-identical titles.

## Endpoint

`POST {base_url}/api/configuration/titles`

`{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 title code, unique within your tenant, and the value member records refer to. Maximum 15 characters. Omit it and the system allocates the next free code with a `TITL` prefix — but the generated code is not returned, so supply your own if you need to know it. Supplied codes are compared case-insensitively and saved upper-cased. A code already in use returns `409` with `The titleId {id} already exists`. |
| `description` | string | Yes | The title as it appears on forms, for example `Mr`. It may not be empty. Validation allows up to 255 characters, **but only 25 can be saved** — anything longer passes validation and then fails with `500` rather than `400`. Treat 25 characters as the real limit. |
| `genderId` | integer (int32) | Yes | The gender this title belongs to, taken from [Get all gender options](get-all-gender-options.md). A value between 0 and 255. It must match an existing gender or the call fails with `400` and `The genderId {value} does not exist`; genders are fixed reference data and are not created for you. |

## Sample request

```bash title="cURL"
curl -X POST '{base_url}/api/configuration/titles' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "string",
  "description": "string",
  "genderId": 12345
}'
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | `description` is empty or longer than 255 characters, or `id` is longer than 15 characters. The body is a validation error object keyed by field name. |
| `400` | Bad request | `genderId` does not match any configured gender — `The genderId {value} does not exist`. |
| `409` | Conflict | A title already exists with the `id` you supplied — `The titleId {id} already exists`. |
| `409` | Conflict | The entry clashes with one that already exists — `This entry already exists in the database`. |
| `500` | Internal server error | Any other failure, including a `description` longer than 25 characters. The body is empty. |