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: '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:
          type: boolean
          description: 'A boolean indicating whether the referrer has opted 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.

            '
        link_url:
          type: string
          description: '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:
          type: boolean
          description: 'A boolean specifying whether the [invitation](/help/invite-new-users) is a

            reusable invitation link or an email invitation.

            '
  responses:
    SimpleSuccess:
      description: Success.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JsonSuccess'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: 'Basic authentication, with the user''s email as the username, and the API

        key as the password. The API key can be fetched using the

        `/fetch_api_key` or `/dev_fetch_api_key` endpoints.

        '