Get all titles with optional filtering

GET /api/configuration/titles

Success: 200 OK

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, Create a new title, Update a title and Delete a title.

Endpoint

GET {base_url}/api/configuration/titles

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

Query parameters

NameTypeRequiredDescription
webVisiblebooleanNoRestricts 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

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

Response fields

FieldTypeDescription
[].idstringThe 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.
[].descriptionstringThe 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.
[].genderIdinteger (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 for the authoritative list, since an operator can add entries beyond the standard five.
[].genderDescriptionstringThe 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.
[].translationsarray of objectLocalised 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[].typestringThe 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[].culturestringThe culture this text belongs to, as a code from the tenant's culture list — see Get all available cultures. Up to 20 characters, and always a culture that exists.
[].translations[].textstringThe translated wording to show in that culture, in place of the untranslated field named by type.
[].webVisiblebooleanWhether 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

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

Errors

StatusMeaningWhen
400Bad requestThe 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.
500Internal server errorAny unexpected server-side failure while loading the titles, their genders or their translations. The body is empty and carries no detail.

This page as markdown · All pages · llms.txt