Create a custom profile field
This endpoint is only available to organization administrators.
POST https://math187awinter2024.zulipchat.com/api/v1/realm/profile_fields
Create a custom profile field in the user's organization.
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")
# Create a custom profile field in the user's organization.
request = {"name": "Phone", "hint": "Contact no.", "field_type": 1}
result = client.call_endpoint(url="/realm/profile_fields", method="POST", request=request)
print(result)
curl -sSX POST https://math187awinter2024.zulipchat.com/api/v1/realm/profile_fields \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode 'name=Favorite programming language' \
--data-urlencode 'hint=Your favorite programming language.' \
--data-urlencode field_type=3 \
--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
Parameters
name string optional
Example: "Favorite programming language"
The name of the custom profile field, which will appear both in
user-facing settings UI for configuring custom profile fields and
in 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_type integer required
Example: 3
The field type can be any of the supported custom profile field types. See the
custom profile fields documentation
for more details on what each type means.
- 1: Short text
- 2: Long text
- 3: List of options
- 4: Date picker
- 5: Link
- 6: Person picker
- 7: External account
- 8: Pronouns
Changes: Field type 8 added in Zulip 6.0 (feature level 151).
field_data object optional
Example: {"python": {"text": "Python", "order": "1"}, "java": {"text": "Java", "order": "2"}}
Field types 3 (List of options) and 7 (External account) support storing
additional configuration for the field type in the field_data attribute.
For field type 3 (List of options), this attribute is a JSON dictionary
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.
display_in_profile_summary boolean optional
Example: true
Whether clients should display this profile field in a 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 "Long text" profile field types
profile field types cannot be selected to be displayed in profile summaries.
The "Person picker" profile field is also not supported, but that is likely to
be temporary.
Changes: 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).
Response
Return values
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:
{
"id": 9,
"msg": "",
"result": "success"
}