Get all invitations

GET https://chat.zulip.org/api/v1/invites

Fetch all unexpired invitations (i.e. email invitations and reusable invitation links) that can be managed by the user.

Note that administrators can manage invitations that were created by other users.

Changes: Prior to Zulip 8.0 (feature level 209), non-admin users could only create email invitations, and therefore the response would never include reusable invitation links for these users.

Usage examples

#!/usr/bin/env python3

import zulip

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

# Get all invitations.
result = client.call_endpoint(url="/invites", method="GET")
print(result)

curl -sSX GET -G https://chat.zulip.org/api/v1/invites \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY

Parameters

This endpoint does not accept any parameters.

Response

Return values

• invites: (object)[]

  An array of objects, each representing a single unexpired invitation.

  • id: integer

    The ID of the invitation.

    Note that email invitations and reusable invitation links are stored in different database tables on the server, so each ID is guaranteed to be unique in combination with the boolean value of is_multiuse, e.g. there can only be one invitation with id: 1 and is_multiuse: true.

  • invited_by_user_id: integer

    The user ID of the user who created the invitation.

    Changes: New in Zulip 3.0 (feature level 22), replacing the ref field which contained the Zulip display email address of the user who created the invitation.

  • invited: integer

    The UNIX timestamp for when the invitation was created, in UTC seconds.

  • expiry_date: integer | null

    The UNIX timestamp for when the invitation will expire, in UTC seconds. If null, the invitation never expires.

  • invited_as: integer

    The organization-level role of the user that is created when the invitation is accepted. Possible values are:

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

  • email: string

    The email address the invitation was sent to. This will not be present when is_multiuse is true (i.e. the invitation is a reusable invitation link).

  • notify_referrer_on_join: boolean

    A boolean indicating whether the referrer has opted to receive a direct message from notification bot when a user account is created using this invitation.

    Changes: New in Zulip 9.0 (feature level 267). Previously, referrers always received such direct messages.

  • link_url: string

    The URL of the reusable invitation link. This will not be present when is_multiuse is false (i.e. the invitation is an email invitation).

  • is_multiuse: boolean

    A boolean specifying whether the invitation is a reusable invitation link or an email invitation.

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:

{
    "invites": [
        {
            "email": "example@zulip.com",
            "expiry_date": null,
            "id": 1,
            "invited": 1710606654,
            "invited_as": 200,
            "invited_by_user_id": 9,
            "is_multiuse": false,
            "notify_referrer_on_join": true
        },
        {
            "expiry_date": 1711463862,
            "id": 1,
            "invited": 1710599862,
            "invited_as": 400,
            "invited_by_user_id": 9,
            "is_multiuse": true,
            "link_url": "https://example.zulipchat.com/join/yddhtzk4jgl7rsmazc5fyyyy/",
            "notify_referrer_on_join": true
        }
    ],
    "msg": "",
    "result": "success"
}