Get a user by email

GET https://qmech2021.zulip.cs.aalto.fi/api/v1/users/{email}

Fetch details for a single user in the organization given a Zulip API email address.

You can also fetch details on all users in the organization or by user ID.

Fetching by user ID is generally recommended when possible, as a user might change their email address or change their email address visibility, either of which could change the client's ability to look them up by that email address.

Changes: Starting with Zulip 10.0 (feature level 302), the real email address can be used in the email parameter and will fetch the target user's data if and only if the target's email visibility setting permits the requester to see the email address. The dummy email addresses of the form user{id}@{realm.host} still work, and will now work for all users, via identifying them by the embedded user ID.

New in Zulip Server 4.0 (feature level 39).

Usage examples

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

result = client.call_endpoint(
    url=f"/users/{email}",
    method="GET",
)
print(result)

curl -sSX GET -G https://qmech2021.zulip.cs.aalto.fi/api/v1/users/iago@zulip.com \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY

curl -sSX GET -G https://qmech2021.zulip.cs.aalto.fi/api/v1/users/iago@zulip.com \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode client_gravatar=false \
    --data-urlencode include_custom_profile_fields=true

Parameters

Response

Return values

• user: object

  A dictionary containing basic data on a given Zulip user.

  Changes: Removed is_billing_admin field in Zulip 10.0 (feature level 363), as it was replaced by the can_manage_billing_group realm setting.

  • user_id: integer

    The unique ID of the user.

  • delivery_email: string | null

    The user's real email address. This value will be null if you cannot access user's real email address. For bot users, this field is always set to the real email of the bot, because bot users always have email_address_visibility set to everyone.

    Changes: Prior to Zulip 7.0 (feature level 163), this field was present only when email_address_visibility was restricted and you had access to the user's real email. As of this feature level, this field is always present, including the case when email_address_visibility is set to everyone (and therefore not restricted).

  • email: string

    The Zulip API email address of the user or bot.

    If you do not have permission to view the email address of the target user, this will be a fake email address that is usable for the Zulip API but nothing else.

  • full_name: string

    Full name of the user or bot, used for all display purposes.

  • date_joined: string

    The time the user account was created.

  • is_active: boolean

    A boolean specifying whether the user account has been deactivated.

  • is_owner: boolean

    A boolean specifying whether the user is an organization owner. If true, is_admin will also be true.

    Changes: New in Zulip 3.0 (feature level 8).

  • is_admin: boolean

    A boolean specifying whether the user is an organization administrator.

  • is_guest: boolean

    A boolean specifying whether the user is a guest user.

  • is_bot: boolean

    A boolean specifying whether the user is a bot or full account.

  • bot_type: integer | null

    An integer describing the type of bot:

    • null if the user isn't a bot.
    • 1 for a Generic bot.
    • 2 for an Incoming webhook bot.
    • 3 for an Outgoing webhook bot.
    • 4 for an Embedded bot.

  • bot_owner_id: integer | null

    If the user is a bot (i.e. is_bot is true), then bot_owner_id is the user ID of the bot's owner (usually, whoever created the bot).

    Will be null for legacy bots that do not have an owner.

    Changes: New in Zulip 3.0 (feature level 1). In previous versions, there was a bot_owner field containing the email address of the bot's owner.

  • role: integer

    Organization-level role of the user. Possible values are:

    • 100 = Organization owner
    • 200 = Organization administrator
    • 300 = Organization moderator
    • 400 = Member
    • 600 = Guest

    Changes: New in Zulip 4.0 (feature level 59).

  • timezone: string

    The IANA identifier of the user's profile time zone, which is used primarily to display the user's local time to other users.

  • avatar_url: string | null

    URL for the user's avatar.

    Will be null if the client_gravatar query parameter was set to true, the current user has access to this user's real email address, and this user's avatar is hosted by the Gravatar provider (i.e. this user has never uploaded an avatar).

    Changes: Before Zulip 7.0 (feature level 163), access to a user's real email address was a realm-level setting. As of this feature level, email_address_visibility is a user setting.

    In Zulip 3.0 (feature level 18), if the client has the user_avatar_url_field_optional capability, this will be missing at the server's sole discretion.

  • avatar_version: integer

    Version for the user's avatar. Used for cache-busting requests for the user's avatar. Clients generally shouldn't need to use this; most avatar URLs sent by Zulip will already end with ?v={avatar_version}.

  • profile_data: object

    Only present if is_bot is false; bots can't have custom profile fields.

    A dictionary containing custom profile field data for the user. Each entry maps the integer ID of a custom profile field in the organization to a dictionary containing the user's data for that field. Generally the data includes just a single value key; for those custom profile fields supporting Markdown, a rendered_value key will also be present.

    • {id}: object

      Object with data about what value the user filled in the custom profile field with that ID.

      • value: string

        User's personal value for this custom profile field.

      • rendered_value: string

        The value rendered in HTML. Will only be present for custom profile field types that support Markdown rendering.

        This user-generated HTML content should be rendered using the same CSS and client-side security protections as are used for message content.

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",
    "user": {
        "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
        "bot_type": null,
        "date_joined": "2019-10-20T07:50:53.729659+00:00",
        "delivery_email": null,
        "email": "hamlet@zulip.com",
        "full_name": "King Hamlet",
        "is_active": true,
        "is_admin": false,
        "is_bot": false,
        "is_guest": false,
        "is_owner": false,
        "profile_data": {
            "1": {
                "rendered_value": "<p>+0-11-23-456-7890</p>",
                "value": "+0-11-23-456-7890"
            },
            "2": {
                "rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>",
                "value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius"
            },
            "3": {
                "rendered_value": "<p>Dark chocolate</p>",
                "value": "Dark chocolate"
            },
            "4": {
                "value": "0"
            },
            "5": {
                "value": "1900-01-01"
            },
            "6": {
                "value": "https://blog.zulig.org"
            },
            "7": {
                "value": "[11]"
            },
            "8": {
                "value": "zulipbot"
            }
        },
        "role": 400,
        "timezone": "",
        "user_id": 10
    }
}