Create a custom profile field

This endpoint is only available to organization administrators.

POST https://zulip.fairsharing.org/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://zulip.fairsharing.org/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

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


Response

Return values

  • id: integer

    The ID for the custom profile field.

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"
}