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

# Bulk Invite to Workspace

> Add several people to your current workspace in one request.

Runs [Invite to Workspace](https://docs.nekt.com/platform-api/invitations/workspace/invite.md) for each entry, and answers with the addresses split by what happened to each.

> [!WARNING]
>
> **All-or-nothing.** One entry that fails, such as a person deactivated in the organization or one already in the workspace with another role, undoes the whole batch: nothing is written and nobody is emailed.

## Request body

| Parameter | Type | Required | Description |
| - | - | - | - |
| `invitations` | array | Yes | The people to invite, each as `{"email", "role", "first_name"?, "last_name"?}`. The same address cannot appear twice. |

## Response

Returns `200 OK`:

```json theme={null}
{
  "message": "Successfully invited 1 user(s) and associated 1 user(s).",
  "invited": ["newcomer@example.com"],
  "resent": [],
  "associated": ["teammate@example.com"]
}
```

| Field | Description |
| - | - |
| `message` | Human-readable summary of what the bulk invite did. |
| `invited` | Addresses invited to the organization from this workspace, pending in it until they accept. |
| `resent` | Addresses whose outstanding invitation was resent from this workspace. |
| `associated` | Addresses already active in the organization, only added to this workspace. Nothing was sent to them. |

## Example

```bash theme={null}
curl --request POST \
  --url https://api.nekt.ai/api/v1/workspace/invitations/bulk-invite/ \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "invitations": [
      {"email": "newcomer@example.com", "role": "member"},
      {"email": "teammate@example.com", "role": "admin"}
    ]
  }'
```

## Authentication

This endpoint requires an [API key](https://docs.nekt.com/platform-api/introduction.md#create-an-api-key) created by a **workspace admin** of the key's workspace. Organization owners and admins are admins of every workspace.

## Errors

Every one of these rejects the **whole** batch.

| Status | When |
| - | - |
| `400` | `invitations` is empty or missing, an entry is malformed, or the same address appears twice. |
| `400` | `already_in_workspace`, `organization_membership_inactive`, or `role_not_allowed_on_free_tier` for any entry. See [Invite to Workspace](https://docs.nekt.com/platform-api/invitations/workspace/invite.md#errors). |
| `403` | The key's creator is not an admin of this workspace. |

## Related

* [Invite to Workspace](https://docs.nekt.com/platform-api/invitations/workspace/invite.md): the single-person version and what each status means.
* [Bulk Invite Users](https://docs.nekt.com/platform-api/invitations/organization/bulk-invite.md): the organization-level bulk invite.


## OpenAPI

````yaml POST /api/v1/workspace/invitations/bulk-invite/
openapi: 3.0.3
info:
  title: Nekt API
  version: v1
  description: Nekt API Documentation
  contact:
    email: support@nekt.ai
servers:
  - url: https://api.nekt.ai
security: []
paths:
  /api/v1/workspace/invitations/bulk-invite/:
    post:
      tags:
        - v1
      description: >-
        Invite several people to your current workspace at once, each exactly as
        a single

        `POST /api/v1/workspace/invitations/` does, and answer their addresses
        split by what happened

        to each.


        All or nothing: one entry that fails (a person inactive in the
        organization, or one already in

        the workspace at another role) undoes the whole batch, and no e-mail
        goes out.
      operationId: v1_workspace_invitations_bulk_invite_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceBulkInvitationInput'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/WorkspaceBulkInvitationInput'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/WorkspaceBulkInvitationInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceBulkInvitationResponse'
          description: ''
      security:
        - ApiKeyAuth: []
components:
  schemas:
    WorkspaceBulkInvitationInput:
      type: object
      description: >-
        Several people to invite to your current workspace, each as a single
        invitation takes one.
      properties:
        invitations:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceInvitationInput'
          description: The people to invite.
      required:
        - invitations
    WorkspaceBulkInvitationResponse:
      type: object
      description: >-
        What a bulk invite to the workspace did, split by what happened to each
        address.
      properties:
        message:
          type: string
          description: Human-readable summary of what the bulk invite did.
        invited:
          type: array
          items:
            type: string
            format: email
          description: >-
            Addresses invited to the organization from this workspace, waiting
            in it until they accept.
        resent:
          type: array
          items:
            type: string
            format: email
          description: >-
            Addresses whose outstanding invitation was re-sent from this
            workspace.
        associated:
          type: array
          items:
            type: string
            format: email
          description: >-
            Addresses already active in the organization, only added to this
            workspace; nothing was sent to them.
      required:
        - associated
        - invited
        - message
        - resent
    WorkspaceInvitationInput:
      type: object
      description: Someone to invite to your current workspace, with their role in it.
      properties:
        email:
          type: string
          format: email
        role:
          allOf:
            - $ref: '#/components/schemas/WorkspaceRoleEnum'
          description: |-
            The person's role in this workspace.

            * `admin` - Admin
            * `member` - Member
        first_name:
          type: string
          default: ''
          maxLength: 150
        last_name:
          type: string
          default: ''
          maxLength: 150
      required:
        - email
        - role
    WorkspaceRoleEnum:
      enum:
        - admin
        - member
      type: string
      description: |-
        * `admin` - Admin
        * `member` - Member
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API Key authentication. Format: ''x-api-key: api_key'''

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.