Create user field configuration

POST /api/configuration/user-fields

Success: 201 Created

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

Overview

Defines a new custom field that can be stored against member records, alongside the standard profile fields. A user field is a definition only — creating one does not populate any member data; you set values per member through the member user field endpoints.

The type you choose is the pivot for the whole request: it decides how defaultValue is parsed, and whether options may be supplied at all. Get that combination wrong and the call is rejected with 400 before anything is written.

A successful call returns 201 Created with an empty body and a Location header pointing at GET /api/configuration/user-fields?ids={newId}. The id of the field you have just created is in that URL, and that call is how you read the stored definition back — the response fields below describe that definition, not a body you will actually receive from this call.

The new field appears on subsequent reads immediately.

Endpoint

POST {base_url}/api/configuration/user-fields

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

Request body

Field	Type	Required	Description
`sortOrder`	integer (int32)	No	Position of the field in the ordered list of user fields. Must be between `0` and `32767`, and must not collide with the sort order of an existing user field — a duplicate is rejected with `400` and `User field sort order is not unique.` Sent as a string rather than a number it fails with `Could not convert string to integer`. Omit it to store no explicit position.
`description`	string	Yes	The field's label, and the name you will see it under everywhere else. Maximum 25 characters; longer values are rejected with `The field Description must be a string with a maximum length of 25.`, and an empty value with `The Description field is required`.
`type`	string (enum)	Yes	One of: `Free_Format`, `Options`, `Date`, `Numeric`, `Currency`, `Hyperlink`, `User`, `Member`. Fixes how `defaultValue` is validated and stored, and whether `options` is permitted — only `Options` accepts them. Missing or unrecognised values are rejected with `The user field type is required to be a non-empty and valid value`.
`defaultValue`	string	No	The value pre-filled when the field is first set on a member. Its accepted shape depends entirely on `type`: a string for `Free_Format` and `Hyperlink`; one of the `options[].description` values for `Options`; a whole number for `Numeric` and a member id for `Member`; a decimal with no currency symbol for `Currency` (`£3.75` is rejected as `not a valid decimal`); an object carrying `DayType`, `MonthType`, `Day`, `Month` and `Year` for `Date`; and an object carrying either a user name or `IsCurrentUser` for `User`. Omit it, or send null, and the field is stored with no default.
`options`	array of object	No	The permitted values, for a `type` of `Options` only. Supplying options with any other type is rejected with `400` and `User field of non-Options type may not have options specified.` Options are stored in the order you send them.
`options[].id`	integer (int32)	No	Ignored on create. Ids are assigned for you, numbering the options `1`, `2`, `3`… in the order they appear in the array, so whatever you send here is discarded.
`options[].description`	string	Yes	The option's text, and the value matched when a member's field is later set — matching is on this exact string, case-sensitively, never on the id. Maximum 50 characters; longer values are rejected with `The field Description must be a string with a maximum length of 50`.

Sample request

cURL

curl -X POST '{base_url}/api/configuration/user-fields' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "sortOrder": 1,
  "description": "string",
  "type": "Free_Format",
  "options": [
    {
      "id": 12345,
      "description": "string"
    }
  ]
}'

Response fields

Field	Type	Description
`sortOrder`	integer (int32)	Position of the field in the ordered list of user fields. Not populated — the `201` response body is empty. Read the field back with `GET /api/configuration/user-fields?ids={id}`, the URL given in the `Location` header.
`description`	string	The field's label, up to 25 characters. Not populated — see the note on `sortOrder`.
`type`	string (enum)	One of: `Free_Format`, `Options`, `Date`, `Numeric`, `Currency`, `Hyperlink`, `User`, `Member`. Not populated — see the note on `sortOrder`.
`defaultValue`	string	The stored default, formatted according to `type`. Not populated — see the note on `sortOrder`.
`options`	array of object	The permitted values, present only for `Options` fields. Not populated — see the note on `sortOrder`.
`options[].id`	integer (int32)	The id assigned to the option, numbered from `1` in array order. Not populated — see the note on `sortOrder`.
`options[].description`	string	The option's text, up to 50 characters. Not populated — see the note on `sortOrder`.

Sample response

201 Created

{
  "sortOrder": 1,
  "description": "string",
  "type": "Free_Format",
  "options": [
    {
      "id": 12345,
      "description": "string"
    }
  ]
}

Errors

Status	Meaning	When
`400`	Bad request	`description` is empty or longer than 25 characters; `type` is missing or not one of the listed values; `sortOrder` is negative, above 32767, non-numeric, or already used by another field (`User field sort order is not unique.`); or an option `description` exceeds 50 characters.
`400`	Bad request	`options` was supplied for a `type` other than `Options` — `User field of non-Options type may not have options specified.`
`400`	Bad request	`defaultValue` does not fit the declared `type`. For example `the given value of: 1234 is not a valid string` (`Free_Format`, `Hyperlink`), `DefaultValue option InvalidValue is not one of the given option descriptions.` (`Options`), `the given value of: invalidvalue is not a valid integer` (`Numeric`), `the given value of: £3.75 is not a valid decimal` (`Currency`), `Invalid or missing data from the default value object.` (`Date`, when a part is missing or malformed), or `Failed to parse NotAnId correctly for its type of Member.` (`Member`).
`400`	Bad request	A `User` default value supplies neither a user name nor `IsCurrentUser` (`User name was not given and IsCurrentUser was not selected.`), or supplies both (`A username cannot be provided when IsCurrentUser is selected.`).
`404`	Not found	A `User` default value names a user that does not exist (`User name InvalidUser was not found.`), or a `Member` default value names a member id that does not exist (`Member ID 9999 was not found.`).
`422`	Unprocessable entity	Returned with an empty body.
`500`	Internal server error	The field could not be saved. Nothing is created, and the request is safe to retry.

This page as markdown · All pages · llms.txt