{{getMsg('Help_YouAreHere')}}: / {{page.title}} {{page.title}}

A A A

User field settings

/api/usersandgroups/user-fields/{key}

Exposes user field settings through the annotation-based WebAPI.

The public representation deliberately contains only scalar metadata and a flat property map. In particular, the manager's internal nature and field implementation are never returned to a client. The map is produced by GenericFieldSetting#toMap and therefore contains generic, user-field-specific, and extension-specific values required for a lossless round trip. Registration of this class is intentionally performed by the owning server plugin.

DELETE /api/usersandgroups/user-fields/{key}

Deletes this setting when it is custom. Registered settings remain owned by their registering plugin and therefore cannot be deleted through this endpoint. Preview validates the same rules and does not mutate the manager.

Parameters

Name	Location	Type	Required	Description
`key`	path	`string`	yes	setting key from the URL

Response

Status	Content Type	Schema	Description
`204`	—	—	No content.

Example Request

# Request
DELETE /api/usersandgroups/user-fields/<key> HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>

# Response
HTTP/1.1 204 No Content

GET /api/usersandgroups/user-fields/{key}

Exposes user field settings through the annotation-based WebAPI.

Parameters

Name	Location	Type	Required	Description
`key`	path	`string`	yes	setting key from the URL
`fields`	query	`string`	no	Comma-separated readable properties to include in the JSON response.

Response

Status	Content Type	Schema	Description
`200`	`application/json`	`UserFieldSettingsRead`	Successful response.

Example Request

# Request
GET /api/usersandgroups/user-fields/<key> HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>

# Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "key": "string",
    "custom": true,
    "properties": {
        "property": "string"
    }
}

PATCH /api/usersandgroups/user-fields/{key}

Exposes user field settings through the annotation-based WebAPI.

Parameters

Name	Location	Type	Required	Description
`key`	path	`string`	yes	setting key from the URL

Request Body

Content Type	Schema	Required	Description
`application/json`	`UserFieldSettingsUpdate`	yes	—

Response

Status	Content Type	Schema	Description
`200`	`application/json`	`UserFieldSettingsRead`	Successful response.

Example Request

# Request
PATCH /api/usersandgroups/user-fields/<key> HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "key": "string",
    "custom": true,
    "properties": {
        "property": "string"
    }
}

# Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "key": "string",
    "custom": true,
    "properties": {
        "property": "string"
    }
}

PUT /api/usersandgroups/user-fields/{key}

Exposes user field settings through the annotation-based WebAPI.

Parameters

Name	Location	Type	Required	Description
`key`	path	`string`	yes	setting key from the URL

Request Body

Content Type	Schema	Required	Description
`application/json`	`UserFieldSettingsUpdate`	yes	—

Response

Status	Content Type	Schema	Description
`200`	`application/json`	`UserFieldSettingsRead`	Successful response.

Example Request

# Request
PUT /api/usersandgroups/user-fields/<key> HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "key": "string",
    "custom": true,
    "properties": {
        "property": "string"
    }
}

# Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "key": "string",
    "custom": true,
    "properties": {
        "property": "string"
    }
}

Common Error Responses

The status codes 400, 403, 404, 405, 406, 409, 413, 415, and 500 use the same ApiError JSON error format:

{
    "status": 404,
    "code": "route_not_found",
    "message": "The requested API route does not exist.",
    "details": []
}

Schemas

Request and response schemas used on this page.