Zulip invites API
The invites API from Zulip — 5 operation(s) for invites.
OpenAPI Specification
openapi: 3.0.1
info:
version: 1.0.0
title: Zulip REST authentication invites API
description: 'Powerful open source group chat
'
contact:
url: https://zulip.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://{subdomain}.zulipchat.com/api/v1
variables:
subdomain:
default: example
- url: '{server}/api/v1'
variables:
server:
default: https://
- url: https://chat.zulip.org/api/v1
- url: http://localhost:9991/api/v1
- url: http://{subdomain}.testserver/json
security:
- basicAuth: []
tags:
- name: invites
paths:
/invites:
get:
operationId: get-invites
summary: Get all invitations
tags:
- invites
description: 'Fetch all unexpired [invitations](/help/invite-new-users) (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.
'
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
invites:
type: array
description: 'An array of objects, each representing a single unexpired
[invitation](/help/invite-new-users).
'
items:
$ref: '#/components/schemas/Invite'
example:
result: success
msg: ''
invites:
- email: example@zulip.com
expiry_date: null
id: 1
invited: 1710606654
invited_as: 200
invited_by_user_id: 9
notify_referrer_on_join: true
is_multiuse: false
- expiry_date: 1711463862
id: 1
invited: 1710599862
invited_as: 400
invited_by_user_id: 9
is_multiuse: true
notify_referrer_on_join: true
link_url: https://example.zulipchat.com/join/yddhtzk4jgl7rsmazc5fyyyy/
post:
operationId: send-invites
summary: Send invitations
tags:
- invites
description: 'Send [invitations](/help/invite-new-users) to specified email addresses.
**Changes**: In Zulip 6.0 (feature level 126), the `invite_expires_in_days`
parameter was removed and replaced by `invite_expires_in_minutes`.
In Zulip 5.0 (feature level 117), added support for passing `null` as
the `invite_expires_in_days` parameter to request an invitation that never
expires.
In Zulip 5.0 (feature level 96), the `invite_expires_in_days` parameter was
added which specified the number of days before the invitation would expire.
'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
invitee_emails:
description: 'The string containing the email addresses, separated by commas or
newlines, that will be sent an invitation.
'
type: string
example: example@zulip.com, logan@zulip.com
invite_expires_in_minutes:
$ref: '#/components/schemas/InviteExpirationParameter'
invite_as:
$ref: '#/components/schemas/InviteRoleParameter'
stream_ids:
description: 'A list containing the [IDs of the channels](/api/get-stream-id) that the
newly created user will be automatically subscribed to if the invitation
is accepted, in addition to any default channels that the new user may
be subscribed to based on the `include_realm_default_subscriptions`
parameter.
Requested channels must either be default channels for the
organization, or ones the acting user has permission to add
subscribers to.
This list must be empty if the current user has the unlikely
configuration of being able to send invitations while lacking
permission to [subscribe other users to channels][can-subscribe-others].
**Changes**: Prior to Zulip 10.0 (feature level 342), default channels
that the acting user did not directly have permission to add
subscribers to would be rejected.
Before Zulip 7.0 (feature level 180), specifying `stream_ids` as an
empty list resulted in an error.
[can-subscribe-others]: /help/configure-who-can-invite-to-channels
'
type: array
items:
type: integer
example:
- 1
- 10
group_ids:
description: 'A list containing the [IDs of the user groups](/api/get-user-groups) that
the newly created user will be automatically added to if the invitation
is accepted. If the list is empty, then the new user will not be
added to any user groups. The acting user must have permission to add users
to the groups listed in this request.
**Changes**: New in Zulip 10.0 (feature level 322).
'
type: array
items:
type: integer
example: []
include_realm_default_subscriptions:
description: 'Boolean indicating whether the newly created user should be subscribed
to the [default channels][default-channels] for the organization.
Note that this parameter can be `true` even if the user creating the
invitation does not generally have permission to [subscribe other
users to channels][can-subscribe-others].
**Changes**: New in Zulip 9.0 (feature level 261). Previous versions
of Zulip behaved as though this parameter was always `false`; clients
needed to include the organization''s default channels in the
`stream_ids` parameter for a newly created user to be automatically
subscribed to them.
[default-channels]: /help/set-default-channels-for-new-users
[can-subscribe-others]: /help/configure-who-can-invite-to-channels
'
type: boolean
default: false
example: false
notify_referrer_on_join:
description: 'A boolean indicating whether the referrer would like to receive a
direct message from [notification
bot](/help/configure-automated-notices) 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.
'
type: boolean
example: false
default: true
welcome_message_custom_text:
description: 'Custom message text, in Zulip Markdown format, to be sent by the
Welcome Bot to new users that join the organization via this
invitation.
Maximum length is 8000 Unicode code points.
Only organization administrators can use this feature; for other
users, the value is always `null`.
- `null`: the organization''s default `welcome_message_custom_text` is used.
- Empty string: no Welcome Bot custom message is sent.
- Otherwise, the provided string is the custom message.
**Changes**: New in Zulip 11.0 (feature level 416).
'
type: string
nullable: true
example: Welcome to Zulip! We're excited to have you on board.
required:
- invitee_emails
- stream_ids
encoding:
invite_expires_in_minutes:
contentType: application/json
stream_ids:
contentType: application/json
group_ids:
contentType: application/json
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
example:
msg: ''
result: success
'400':
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: '#/components/schemas/InvitationFailedError'
- example:
result: error
msg: Some of those addresses are already using Zulip, so we didn't send them an invitation. We did send invitations to everyone else!
errors:
- - hamlet@zulip.com
- Already has an account.
- false
sent_invitations: true
license_limit_reached: false
daily_limit_reached: false
code: INVITATION_FAILED
description: 'An example JSON error response for when some of the specified email addresses
have existing Zulip accounts.
'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
code: BAD_REQUEST
msg: Insufficient permission
result: error
description: 'An example JSON error response for when the user doesn''t have permission
to send invitations.
'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
code: BAD_REQUEST
msg: You must specify at least one email address.
result: error
description: 'An example JSON error response for when no email address is specified.
'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
code: BAD_REQUEST
msg: Invalid channel ID 11. No invites were sent.
result: error
description: 'An example JSON error response for when any of the specified channels
does not exist or the user does not have permission to access one of
the targeted channels.
'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
code: BAD_REQUEST
msg: You do not have permission to subscribe other users to channels.
result: error
description: 'An example JSON error response for when the user doesn''t have permission
to subscribe other users to channels and `stream_ids` is not empty.
'
/invites/multiuse:
post:
operationId: create-invite-link
summary: Create a reusable invitation link
tags:
- invites
description: 'Create a [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link)
which can be used to invite new users to the organization.
**Changes**: In Zulip 8.0 (feature level 209), added support for non-admin
users [with permission](/help/restrict-account-creation#change-who-can-send-invitations)
to use this endpoint. Previously, it was restricted to administrators only.
In Zulip 6.0 (feature level 126), the `invite_expires_in_days`
parameter was removed and replaced by `invite_expires_in_minutes`.
In Zulip 5.0 (feature level 117), added support for passing `null` as
the `invite_expires_in_days` parameter to request an invitation that never
expires.
In Zulip 5.0 (feature level 96), the `invite_expires_in_days` parameter was
added which specified the number of days before the invitation would expire.
'
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
invite_expires_in_minutes:
$ref: '#/components/schemas/InviteExpirationParameter'
invite_as:
$ref: '#/components/schemas/InviteRoleParameter'
stream_ids:
description: 'A list containing the [IDs of the channels](/api/get-stream-id) that the
newly created user will be automatically subscribed to if the invitation
is accepted, in addition to any default channels that the new user may
be subscribed to based on the `include_realm_default_subscriptions`
parameter.
Requested channels must either be default channels for the
organization, or ones the acting user has permission to add
subscribers to.
This list must be empty if the current user has the unlikely
configuration of being able to create reusable invitation links while
lacking permission to [subscribe other users to
channels][can-subscribe-others].
**Changes**: Prior to Zulip 10.0 (feature level 342), default channels
that the acting user did not directly have permission to add
subscribers to would be rejected.
[can-subscribe-others]: /help/configure-who-can-invite-to-channels
'
type: array
items:
type: integer
default: []
example:
- 1
- 10
group_ids:
description: 'A list containing the [IDs of the user groups](/api/get-user-groups) that
the newly created user will be automatically added to if the invitation
is accepted. If the list is empty, then the new user will not be
added to any user groups. The acting user must have permission to add users
to the groups listed in this request.
**Changes**: New in Zulip 10.0 (feature level 322).
'
type: array
items:
type: integer
default: []
example: []
include_realm_default_subscriptions:
description: 'Boolean indicating whether the newly created user should be subscribed
to the [default channels][default-channels] for the organization.
Note that this parameter can be `true` even if the current user does
not generally have permission to [subscribe other users to
channels][can-subscribe-others].
**Changes**: New in Zulip 9.0 (feature level 261). Previous versions
of Zulip behaved as though this parameter was always `false`; clients
needed to include the organization''s default channels in the
`stream_ids` parameter for a newly created user to be automatically
subscribed to them.
[default-channels]: /help/set-default-channels-for-new-users
[can-subscribe-others]: /help/configure-who-can-invite-to-channels
'
type: boolean
default: false
example: false
welcome_message_custom_text:
description: 'Custom message text, in Zulip Markdown format, to be sent by the
Welcome Bot to new users that join the organization via this
invitation.
Maximum length is 8000 Unicode code points.
Only organization administrators can use this feature; for other
users, the value is always `null`.
- `null`: the organization''s default `welcome_message_custom_text` is used.
- Empty string: no Welcome Bot custom message is sent.
- Otherwise, the provided string is the custom message.
**Changes**: New in Zulip 11.0 (feature level 416).
'
type: string
nullable: true
example: Welcome to Zulip! We're excited to have you on board.
encoding:
invite_expires_in_minutes:
contentType: application/json
stream_ids:
contentType: application/json
group_ids:
contentType: application/json
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
invite_link:
type: string
description: 'The URL of the [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link)
that was created by this request.
'
example:
result: success
msg: ''
invite_link: https://example.zulipchat.com/join/yddhtzk4jgl7rsmazc5fyyyy/
'400':
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
code: BAD_REQUEST
msg: Insufficient permission
result: error
description: 'An example JSON error response for when the user doesn''t have permission
to send invitations.
'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
code: BAD_REQUEST
msg: Invalid channel ID 11. No invites were sent.
result: error
description: 'An example JSON error response for when any of the specified channels
does not exist or the user does not have permission to access one of
the targeted channels.
'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
code: BAD_REQUEST
msg: You do not have permission to subscribe other users to channels.
result: error
description: 'An example JSON error response for when the user doesn''t have permission
to subscribe other users to channels and `stream_ids` is not empty.
'
/invites/{invite_id}:
delete:
operationId: revoke-email-invite
summary: Revoke an email invitation
tags:
- invites
description: 'Revoke an [email invitation](/help/invite-new-users#send-email-invitations).
A user can only revoke [invitations that they can
manage](/help/invite-new-users#manage-pending-invitations).
'
parameters:
- name: invite_id
in: path
description: 'The ID of the email invitation to be revoked.
'
schema:
type: integer
example: 1
required: true
responses:
'200':
$ref: '#/components/responses/SimpleSuccess'
'400':
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
result: error
msg: No such invitation
code: BAD_REQUEST
description: 'A typical failed JSON response for an invalid email invitation ID:
'
/invites/multiuse/{invite_id}:
delete:
operationId: revoke-invite-link
summary: Revoke a reusable invitation link
tags:
- invites
description: 'Revoke a [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link).
A user can only revoke [invitations that they can
manage](/help/invite-new-users#manage-pending-invitations).
**Changes**: Prior to Zulip 8.0 (feature level 209), only organization
administrators were able to create and revoke reusable invitation links.
'
parameters:
- name: invite_id
in: path
description: 'The ID of the reusable invitation link to be revoked.
'
schema:
type: integer
example: 1
required: true
responses:
'200':
$ref: '#/components/responses/SimpleSuccess'
'400':
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
result: error
msg: No such invitation
code: BAD_REQUEST
description: 'A typical failed JSON response for an invalid invitation link ID:
'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
result: error
msg: Invitation has already been revoked
code: BAD_REQUEST
description: 'A typical failed JSON response for when the invitation link has already
been revoked:
'
/invites/{invite_id}/resend:
post:
operationId: resend-email-invite
summary: Resend an email invitation
tags:
- invites
description: 'Resend an [email invitation](/help/invite-new-users#send-email-invitations).
A user can only resend [invitations that they can
manage](/help/invite-new-users#manage-pending-invitations).
'
parameters:
- name: invite_id
in: path
description: 'The ID of the email invitation to be resent.
'
schema:
type: integer
example: 1
required: true
responses:
'200':
$ref: '#/components/responses/SimpleSuccess'
'400':
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
result: error
msg: No such invitation
code: BAD_REQUEST
description: 'A typical failed JSON response for an invalid email invitation ID:
'
components:
schemas:
JsonSuccessBase:
description: '**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`][ignored_params] array.
A typical successful JSON response may look like:
[ignored_params]: /api/rest-error-handling#ignored-parameters
'
allOf:
- $ref: '#/components/schemas/JsonResponseBase'
- required:
- result
- msg
properties:
result:
enum:
- success
msg:
type: string
ignored_parameters_unsupported:
$ref: '#/components/schemas/IgnoredParametersUnsupported'
InviteRoleParameter:
description: 'The [organization-level role](/api/roles-and-permissions) 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
Users can only create invitation links for
[roles with equal or stricter restrictions](/api/roles-and-permissions#permission-levels)
as their own. For example, a moderator cannot invite someone to be an owner
or administrator, but they can invite them to be a moderator or member.
**Changes**: In Zulip 4.0 (feature level 61), added support for inviting
users as moderators.
'
type: integer
enum:
- 100
- 200
- 300
- 400
- 600
default: 400
example: 600
JsonSuccess:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
example:
msg: ''
result: success
InviteExpirationParameter:
description: 'The number of minutes before the invitation will expire. If `null`, the
invitation will never expire. If unspecified, the server will use a default
value (based on the `INVITATION_LINK_VALIDITY_MINUTES` server setting, which
defaults to 14400, i.e. 10 days) for when the invitation will expire.
**Changes**: New in Zulip 6.0 (feature level 126). Previously, there was an
`invite_expires_in_days` parameter, which specified the duration in days instead
of minutes.
'
type: integer
nullable: true
example: 14400
IgnoredParametersUnsupported:
type: array
items:
type: string
description: 'An array of any parameters sent in the request that are not
supported by the endpoint.
See [error handling](/api/rest-error-handling#ignored-parameters) documentation
for details on this and its change history.
'
JsonResponseBase:
type: object
properties:
result:
type: string
InvitationFailedError:
allOf:
- $ref: '#/components/schemas/CodedErrorBase'
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
errors:
type: array
items:
type: array
items:
oneOf:
- type: string
- type: boolean
description: 'An array of arrays of length 3, where each inner array consists of (a) an email
address that was skipped while sending invitations, (b) the corresponding error
message, and (c) a boolean which is `true` when the email address already uses Zulip
and the corresponding user is deactivated in the organization.
'
sent_invitations:
description: 'A boolean specifying whether any invitations were sent.
'
type: boolean
daily_limit_reached:
type: boolean
description: 'A boolean specifying whether the limit on the number of invitations that can
be sent in the organization in a day has been reached.
'
license_limit_reached:
type: boolean
description: 'A boolean specifying whether the organization have enough unused Zulip licenses
to invite specified number of users.
'
CodedError:
allOf:
- $ref: '#/components/schemas/CodedErrorBase'
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
CodedErrorBase:
allOf:
- $ref: '#/components/schemas/JsonResponseBase'
- required:
- result
- msg
- code
properties:
result:
enum:
- error
msg:
type: string
code:
type: string
description: 'A string that identifies the error.
'
Invite:
type: object
description: 'A dictionary containing details about an [invitation](/help/invite-new-users).
'
additionalProperties: false
properties:
id:
type: integer
description: '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:
type: integer
description: 'The [user ID](/api/get-user) 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:
type: integer
description: 'The UNIX timestamp for when the invitation was created, in UTC seconds.
'
expiry_date:
type: integer
nullable: true
description: 'The UNIX timestamp for when the invitation will expire, in UTC seconds.
If `null`, the invitation never expires.
'
invited_as:
type: integer
enum:
- 100
- 200
- 300
- 400
- 600
description: 'The [organization-level role](/api/roles-and-permissions) 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:
type: string
description: 'Th
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zulip/refs/heads/main/openapi/zulip-invites-api-openapi.yml