Updates a title

PUT /api/configuration/titles/{titleId}

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

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

Path parameters

Name	Type	Required	Description
`titleId`	string	Yes	The title's identifier, as returned in `[].id` by List titles. 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

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.

This page as markdown · All pages · llms.txt