# Updates a title

`PUT /api/configuration/titles/{titleId}`

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

HTML version: [Updates a title](https://support.gladstonesoftware.cloud/reference/configuration/updates-a-title)

## Overview

Updates a personal title — the `Mr`, `Ms`, `Dr` prefix offered when capturing a member's name — and the gender it implies.

**This is a merge for the text and a replacement for the gender.** `description` is written only when you send a non-empty value, so omitting it, sending null, or sending an empty string all mean "leave the stored text alone". `genderId` is required on every call, so you must always state the gender even when you only want to reword the title.

**The gender cannot be changed once any member holds the title.** If your `genderId` differs from the stored one, the call is refused with `409` when at least one member record uses this title. Sending the same `genderId` back is always accepted, so a description-only change works on a title that is in use.

**Two things to watch:**

- **An unknown `titleId` returns `400`, not `404`.** The message is `The titleId {titleId} does not exists`.
- **`description` is validated at 255 characters but only 25 are accepted.** Anything between 26 and 255 characters passes validation and then fails with `500`. Keep titles to 25 characters — in practice they are a few characters long.

Read the current values with [Get title by ID](get-a-specific-title-by-id.md) first. A successful update returns `204 No Content`.

## Endpoint

`PUT {base_url}/api/configuration/titles/{titleId}`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `titleId` | string | Yes | The title's identifier, as returned in `[].id` by [List titles](get-all-titles-with-optional-filtering.md). Maximum 15 characters, and matched case-insensitively, so `mr` and `MR` reach the same title. An id matching no title is rejected with `400` and `The titleId {titleId} does not exists`. |

## Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `description` | string | No | The title as it is displayed and offered in name-capture forms — `Mr`, `Mrs`, `Dr`. **Effectively limited to 25 characters**: validation permits 255 but only 25 are accepted, so anything longer fails as a `500` rather than a `400`. Omitting it, sending null, or sending an empty string all leave the stored text unchanged — there is no way to clear it. |
| `genderId` | integer (int32) | Yes | The gender this title implies, so that selecting a title can populate a member's gender. The shipped values are `0` Male, `1` Female, `2` Unknown, `3` Other and `4` Prefer not to say; confirm your environment's list before hard-coding them. Required on every call — there is no "leave unchanged", so resend the stored value when you are only editing `description`. A value above 255 is rejected. If the value differs from the stored one it must reference an existing gender (`The genderId {id} does not exist`, `400`) and no member may currently hold the title (`409`). |

## Sample request

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

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | No title has that `titleId` — `The titleId {titleId} does not exists`. This endpoint has no `404`. |
| `400` | Bad request | `genderId` is absent, or `description` exceeds 255 characters — `The title description cannot be more than 255 characters`, returned as a validation error object keyed by field name. |
| `400` | Bad request | `genderId` differs from the stored value and does not reference an existing gender — `The genderId {genderId} does not exist`. |
| `409` | Conflict | `genderId` differs from the stored value and at least one member holds this title — `The title {titleId}'s genderId cannot be changed as it is in use`. Resend the stored `genderId` to change `description` instead. |
| `500` | Internal server error | `description` is longer than 25 characters, or any other unexpected server-side failure. The response body is empty. |