> ## Documentation Index
> Fetch the complete documentation index at: https://docs.claap.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Invite users

> Invite users to the workspace by email. Each email gets its own result: an email that cannot be invited does not prevent the others from being invited.

Invites up to 50 people to the workspace by email. The invite email is sent on behalf of the person who created the API key.

Each email gets its own `outcome`:

* `invited`: an invite was created, the user joins the workspace when they accept it.
* `added`: the email already has a Claap account, the user was added to the workspace right away.
* `already_member`: the email is already an active user of the workspace.
* `failed`: the email could not be invited, for instance because it is not valid, the user is suspended, or the invite limit is reached for that workspace. `error` explains why.


## OpenAPI

````yaml POST /v1/invites
openapi: 3.1.0
info:
  title: Claap API
  description: Development documentation
  version: 0.0.0
servers:
  - url: https://api.claap.io/
security:
  - ApiKey: []
paths:
  /v1/invites:
    post:
      description: >-
        Invite users to the workspace by email. Each email gets its own result:
        an email that cannot be invited does not prevent the others from being
        invited.
      operationId: postV1Invites
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                emails:
                  type: array
                  items:
                    type: string
                    format: email
                  minItems: 1
                  maxItems: 50
                  description: Emails to invite.
                role:
                  type: string
                  enum:
                    - Member
                    - Admin
                    - Owner
                  default: Member
                  description: >-
                    Role given to the invited users. On a workspace without an
                    active subscription, users are always invited as Owner.
                userGroupIds:
                  type: array
                  items:
                    type: string
                  description: User groups the invited users join.
                message:
                  type: string
                  description: Personal message added to the invite email.
              required:
                - emails
            example:
              emails:
                - jane.doe@example.com
                - john.smith@example.com
                - alex.martin@example.com
              role: Member
              message: Welcome to the team!
      responses:
        '200':
          description: Invites were processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      results:
                        type: array
                        items:
                          type: object
                          properties:
                            email:
                              type: string
                              description: Invited email.
                            outcome:
                              type: string
                              enum:
                                - invited
                                - added
                                - already_member
                                - failed
                              description: >-
                                "invited" when an invite was created, "added"
                                when the email has a Claap account in another
                                workspace and was added to the workspace right
                                away, "already_member" when the email is already
                                an active user of the workspace, "failed" when
                                this email could not be invited.
                            error:
                              type: string
                              description: >-
                                Why the email could not be invited, set only
                                when the outcome is "failed".
                            userId:
                              type: string
                              description: >-
                                User identifier, set only when the outcome is
                                "added" or "already_member".
                          required:
                            - email
                            - outcome
                        description: One result per unique email.
                    required:
                      - results
                required:
                  - result
              example:
                result:
                  results:
                    - email: jane.doe@example.com
                      outcome: invited
                    - email: john.smith@example.com
                      outcome: already_member
                      userId: Xk2Rd7Mv4Bn9Ts1Lq6Wf3
                    - email: alex.martin@example.com
                      outcome: failed
                      error: Cannot invite suspended user
        '400':
          description: >-
            The request is not valid. For instance an email is malformed, more
            than 50 emails are provided, or a user group was not found.
        '403':
          description: >-
            The invites are not allowed. For instance more than 10 emails are
            provided and the workspace plan does not allow it, or user editing
            is restricted by SCIM provisioning.
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-Claap-Key

````