Update a custom profile field
This endpoint is only available to organization administrators.
PATCH https://chat.dispatchbutler.com/api/v1/realm/profile_fields/{field_id}
Update the configuration of a
custom profile field in the user's
organization.
The type
of a custom profile field cannot be changed.
At most, 2 custom profile fields can have
display_in_profile_summary
set to true in an organization.
For custom profile fields with type 7 (External account) that use
one of Zulip's configured default external account providers
(e.g., GitHub, LinkedIn, etc.), the field's
name,
hint, and
field_data
cannot be changed, and attempting to do so will return an error.
Changes: Before Zulip 9.0 (feature level 252), the name,
hint, field_data, required and display_in_profile_summary
parameters were all required in every request, even when their
values were unchanged.
Usage examples
#!/usr/bin/env python
import zulip
# The user for this zuliprc file must be an organization administrator
client = zulip.Client(config_file="~/zuliprc-admin")
# Update a custom profile field in the user's organization.
request = {"name": "Cell", "hint": "Contact number."}
result = client.call_endpoint(
url=f"/realm/profile_fields/{field_id}", method="PATCH", request=request
)
print(result)
The -u line implements HTTP Basic authentication.
See the Authorization header documentation for how
to get those credentials for Zulip users and bots.
curl -sSX PATCH https://chat.dispatchbutler.com/api/v1/realm/profile_fields/4 \
-u EMAIL_ADDRESS:API_KEY \
--data-urlencode 'name=Programming language' \
--data-urlencode 'hint=Your favorite programming language.' \
--data-urlencode 'field_data={"java": {"order": "2", "text": "Java"}, "python": {"order": "1", "text": "Python"}}' \
--data-urlencode display_in_profile_summary=true \
--data-urlencode required=true \
--data-urlencode editable_by_user=true \
--data-urlencode use_for_user_matching=false
Parameters
field_id integer required in path
Example: 4
The ID of the target custom profile field.
name string optional
Example: "Programming language"
The name of the custom profile field, which appears both in
the user-facing settings UI for configuring the custom profile
fields and in the UI displaying a user's profile.
hint string optional
Example: "Your favorite programming language."
The help text to be displayed for the custom profile field in user-facing
settings UI for configuring custom profile fields.
field_data object optional
Example: {"python": {"text": "Python", "order": "1"}, "java": {"text": "Java", "order": "2"}}
Field types 3 (Dropdown) and 7 (External account) support storing
additional configuration for the field type in the field_data attribute.
For field type 3 (Dropdown), this attribute is a JSON object
defining the choices and the order they will be displayed in the
dropdown UI for individual users to select an option.
The interface for field type 7 is not yet stabilized.
See profile field types
or the field_type parameter
for what each field type number means.
display_in_profile_summary boolean optional
Example: true
Whether clients should display this profile field in the summary section of a
user's profile (or in a more easily accessible "small profile").
At most 2 profile fields may have this property be true in a given
organization.
The "Users" profile field is not supported, but that is likely to
be temporary.
Changes: Before Zulip 12.0 (feature level 476), the
"Paragraph" field type was not supported.
New in Zulip 6.0 (feature level 146).
required boolean optional
Example: true
Whether an organization administrator has configured this profile field as
required.
Because the required property is mutable, clients cannot assume that a required
custom profile field has a value. The Zulip web application displays a prominent
banner to any user who has not set a value for a required field.
Changes: New in Zulip 9.0 (feature level 244).
editable_by_user boolean optional
Example: true
Whether regular users can edit this profile field on their own account.
Note that organization administrators can edit custom profile fields for any user
regardless of this setting.
Changes: New in Zulip 10.0 (feature level 296).
use_for_user_matching boolean optional
Example: false
Whether this custom profile field should be used to match users in typeahead
suggestions. Only allowed for Short Text and External Account
profile field types.
This field is only included when its value is true.
Changes: New in Zulip 12.0 (feature level 455).
Response
Example response(s)
Changes: As of Zulip 7.0 (feature level 167), if any
parameters sent in the request are not supported by this
endpoint, a successful JSON response will include an
ignored_parameters_unsupported array.
A typical successful JSON response may look like:
{
"msg": "",
"result": "success"
}
A typical failed JSON response for when there is no custom profile
field with the requested ID:
{
"code": "BAD_REQUEST",
"msg": "Field id 4 not found.",
"result": "error"
}
A typical failed JSON response for when another custom profile field
already uses the requested name:
{
"code": "BAD_REQUEST",
"msg": "A field with that label already exists.",
"result": "error"
}
A typical failed JSON response for when setting
display_in_profile_summary to true would exceed the
organization's limit of 2 such fields:
{
"code": "BAD_REQUEST",
"msg": "Only 2 custom profile fields can be displayed in the profile summary.",
"result": "error"
}
A typical failed JSON response for when attempting to change the
name, hint, or field_data of a default external account field:
{
"code": "BAD_REQUEST",
"msg": "Default custom field cannot be updated.",
"result": "error"
}