# Get all titles with optional filtering

`GET /api/configuration/titles`

- **Success:** `200 OK`
- **Products:** Operator (`FOH`), Consumer (`CONSUMER`) (any one of these products, not all)
- **Features:** Online Joining (`ONLINEJOIN`), Online Bookings (`ONLINEBOOK`), Front of House Generic Access (`FOHGENERIC`) (any one of these features, not all)

HTML version: [Get all titles with optional filtering](https://support.gladstonesoftware.cloud/reference/configuration/get-all-titles-with-optional-filtering)

## Overview

Returns the personal titles — Mr, Mrs, Dr and so on — that this operator accepts on a member record. Use it to populate the title dropdown on any registration or profile form you build, and to validate a title before you send it to a member-creating endpoint. The `id` values it returns are the ones the member APIs expect.

**Title ids are operator-defined, not a fixed platform list.** They are strings of up to 15 characters, unique within one tenant and meaningless outside it. They are always returned in upper case, regardless of how they were entered. A standard installation starts with `DR`, `MAST`, `MISS`, `MR`, `MRS`, `MS`, `PROF` and `UNKNO`, but an operator may have edited, removed or added to that list, and only `UNKNO` is guaranteed to exist. Titles created through the API without an explicit id are given a generated one beginning `TITL`. Never hardcode a title id; read it from here.

Every title in the tenant is returned. There is no inactive, archived or soft-delete flag on a title, so nothing is hidden from you — a title only disappears when it is genuinely deleted. `webVisible` is the closest thing to a status flag, and it is the only filter this endpoint offers.

`webVisible` is also effectively read-only. It defaults to on for every new title and neither the create nor the update endpoint accepts a value for it, so unless it has been changed outside the API you should expect every title to come back `true`. Do not treat a call filtered to `webVisible=false` returning nothing as a fault.

When nothing matches — including when the tenant has no titles at all — the response is `200` with an empty array `[]`. There is no `204` and no `404`.

Titles changed outside the API may not appear here for some time.

Related: [Get a specific title by ID](get-a-specific-title-by-id.md), [Create a new title](create-a-new-title.md), [Update a title](updates-a-title.md) and [Delete a title](deletes-a-title.md).

## Endpoint

`GET {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).

## Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `webVisible` | boolean | No | Restricts the result to titles whose `webVisible` flag equals the value you send. Omit it — the default — and every title is returned regardless of the flag. Because the flag defaults to on and cannot be set through the API, `webVisible=true` normally returns the same list as omitting the parameter, and `webVisible=false` normally returns `[]`. A value that does not parse as a boolean is rejected with a `400`. |

## Sample request

```bash title="cURL"
curl -X GET '{base_url}/api/configuration/titles' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'
```

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `[].id` | string | The title's identifier, and the value member-creating and member-updating endpoints expect for a member's title. Operator-defined, up to 15 characters, and always upper case in the response — a title entered as `mr` comes back as `MR`. Unique within the tenant and meaningless outside it. |
| `[].description` | string | The title as it should be displayed — `Mr`, `Professor`, `Prefer not to say`. Maximum 25 characters, even though the create and update endpoints accept up to 255 in validation and then fail on anything longer than 25. Nullable, so a badly configured title can come back with no display text at all; fall back to `id` rather than rendering an empty option. |
| `[].genderId` | integer (int32) | The gender this title implies, as an id from the platform's gender list. These ids are the same in every tenant: `0` Male, `1` Female, `2` Unknown, `3` Other, `4` Prefer not to say. Use it to pre-select a gender when a member picks a title. See [Get all gender options](get-all-gender-options.md) for the authoritative list, since an operator can add entries beyond the standard five. |
| `[].genderDescription` | string | The display text of the linked gender, taken from the linked gender rather than the title — `Male`, `Female`, `Unknown` and so on, up to 25 characters. Supplied so you do not have to call the genders endpoint just to label a title. Untranslated: this field carries the operator's configured wording, not a localised one. |
| `[].translations` | array of object | Localised text for this title, one entry per translated property per culture. Always an array — never null — and empty when the title has no translations, which is the normal case on an English-only installation. |
| `[].translations[].type` | string | The name of the title property this entry translates, typically the field behind `description`. Despite the field name it is not a category of translation: it holds the property name, up to 50 characters. Apply it by overwriting the field it names. |
| `[].translations[].culture` | string | The culture this text belongs to, as a code from the tenant's culture list — see [Get all available cultures](get-all-available-cultures.md). Up to 20 characters, and always a culture that exists. |
| `[].translations[].text` | string | The translated wording to show in that culture, in place of the untranslated field named by `type`. |
| `[].webVisible` | boolean | Whether the operator has marked this title as one to offer on web-facing forms. Never null and defaults to on, and no endpoint in this API can change it, so in practice it is `true` for every title unless it was changed outside the API. Treat it as a hint rather than a permission: nothing stops you sending a title with `webVisible` false when creating a member. |

## Sample response

```json title="200 OK"
[
  {
    "id": "string",
    "description": "string",
    "genderId": 12345,
    "genderDescription": "string",
    "translations": [
      {
        "type": "string",
        "culture": "string",
        "text": "string"
      }
    ],
    "webVisible": true
  }
]
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | The `webVisible` value could not be parsed as a boolean. The body is a validation problem document (`application/problem+json`) rather than a plain message. The endpoint has no other validation and no other cause of `400` — omitting the parameter is always valid. |
| `500` | Internal server error | Any unexpected server-side failure while loading the titles, their genders or their translations. The body is empty and carries no detail. |