> ## 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 Users

> Invite several people to your organization, and its workspaces, in one request.

Invites a list of people in one call. Every entry behaves exactly like a single [Invite User](https://docs.nekt.com/platform-api/invitations/organization/invite.md) request, `workspaces` included: an address with no outstanding invitation is invited, and one that already has an invitation gets it resent, with a role change if the role differs. This is the common integration case for onboarding a team from a list.

> [!WARNING]
>
> **All-or-nothing.** One bad entry undoes the whole batch: nothing is written and nobody is emailed. Applying some entries and reporting the rest would make a retry ambiguous, and re-sending the batch would mail everyone who already succeeded a second time.

## Request body

| Parameter | Type | Required | Description |
| - | - | - | - |
| `invitations` | array | Yes | The people to invite. Each entry has the same shape as a single invite. |

Each entry in `invitations` accepts:

| Field | Type | Required | Description |
| - | - | - | - |
| `email` | string | Yes | The address to invite. Normalized before storing, so casing never creates a duplicate. |
| `organization_role` | string | No | One of `owner`, `admin`, or `member`. Defaults to `member`. |
| `workspaces` | array | No | Workspaces to place the invitee in, each as `{"workspace": "<workspace id>", "role": "admin" \| "member"}`. Omit it for owners and admins, who are admins of every workspace. |
| `first_name` | string | No | Shown in the member list before the person accepts. |
| `last_name` | string | No | Shown in the member list before the person accepts. |
| `functional_area` | string | No | The invitee's functional area. |
| `other_functional_area` | string | No | Free-text functional area, when none of the predefined options fit. |

## Response

Returns `200 OK` with a summary of what the batch did, split by what happened to each address.

```json theme={null}
{
  "message": "Successfully invited 2 user(s).",
  "invited": ["analyst@example.com", "lead@example.com"],
  "resent": []
}
```

| Field | Description |
| - | - |
| `message` | Human-readable summary of what the bulk invite did. |
| `invited` | Addresses that had no outstanding invitation and now do. |
| `resent` | Addresses whose outstanding invitation was resent. |

`invited` and `resent` together always account for every entry you sent.

## Example

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

## Python example: onboard a team into a workspace

```python theme={null}
import os

import requests

BASE_URL = "https://api.nekt.ai"
WORKSPACE_ID = "3f6c2a1e-9b4d-4c7a-8e21-5d0b7a9c4e12"
headers = {
    "x-api-key": os.environ["NEKT_API_KEY"],
    "Content-Type": "application/json",
}

emails = ["analyst@example.com", "scientist@example.com", "lead@example.com"]

response = requests.post(
    f"{BASE_URL}/api/v1/organization/invitations/bulk-invite/",
    headers=headers,
    # `organization_role` omitted, so everyone comes in as a member of the organization.
    json={
        "invitations": [
            {"email": email, "workspaces": [{"workspace": WORKSPACE_ID, "role": "member"}]}
            for email in emails
        ]
    },
)
response.raise_for_status()

body = response.json()
print(f"invited: {body['invited']}")
print(f"resent:  {body['resent']}")
```

## Resending

Sending the same batch again is safe and is how you chase people who have not accepted. Nobody is duplicated: addresses that already have an invitation come back under `resent` with a fresh expiry, and their existing groups and grants are untouched.

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

> [!TIP]
>
> If an entry names a different `organization_role` than the outstanding invitation has, the resend moves the person to it on both the invitation and their pending membership. Moving an existing `admin` or `owner` requires an owner.

## Authentication

This endpoint requires an [API key](https://docs.nekt.com/platform-api/introduction.md#create-an-api-key) in the `x-api-key` header.

Only an organization **owner or admin** can invite, and nobody can invite somebody to an organization role above their own. For an API key, that ceiling is read from the organization role of the user who created the key, and `workspaces` can only name the key's own workspace.

## Errors

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

| Status | When |
| - | - |
| `400` | An address already belongs to an active member of the organization. |
| `400` | The same address appears twice in one payload. |
| `400` | `invitations` is empty or missing, or an entry has no `email`. |
| `400` | An entry's `workspaces` names a workspace that is not available, names one twice, or is inconsistent with an owner or admin role (`workspaces_inconsistent_with_role`). |
| `403` | The caller is a member, or an entry names an organization role above the caller's own. |
| `403` | The organization is on the Free plan, where only owners may be invited. |

> [!TIP]
>
> Because one bad entry rejects everything, a long list built from an external source is worth filtering first: drop addresses that are already members, and de-duplicate. A rejected batch tells you what was wrong, but it writes nothing.

## Related

* [Invite User](https://docs.nekt.com/platform-api/invitations/organization/invite.md): invite or resend for a single person.
* [Bulk Invite to Workspace](https://docs.nekt.com/platform-api/invitations/workspace/bulk-invite.md): the same, scoped to your current workspace, for workspace admins.
* [Onboarding flow](https://docs.nekt.com/platform-api/invitations/overview.md): invite, group, and grant before somebody accepts.
* [List Invitations](https://docs.nekt.com/platform-api/invitations/organization/list.md): what is still outstanding.


## OpenAPI

````yaml POST /api/v1/organization/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/organization/invitations/bulk-invite/:
    post:
      tags:
        - v1
      description: >-
        Invite several people at once.


        Each entry behaves exactly like a single `POST
        /api/v1/organization/invitations/`,

        `workspaces` included: an address with no outstanding invitation is
        invited, and one that

        already has an invitation gets it re-sent, with a role change if the
        role differs. Only

        `email` is required; `organization_role` defaults to `member`.


        ALL-OR-NOTHING: one entry that fails undoes the whole batch, and the
        e-mails are sent on

        commit, so a batch that rolls back sends none.
      operationId: v1_organization_invitations_bulk_invite_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationBulkInvitationInput'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OrganizationBulkInvitationInput'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OrganizationBulkInvitationInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkInvitationResponse'
          description: ''
      security:
        - ApiKeyAuth: []
components:
  schemas:
    OrganizationBulkInvitationInput:
      type: object
      description: >-
        `organization/invitations/bulk-invite/` input: several invitations, each
        as

        `POST organization/invitations/` takes one, `workspaces` included.
      properties:
        invitations:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationInvitation'
          description: The people to invite.
      required:
        - invitations
    BulkInvitationResponse:
      type: object
      description: What a bulk invite 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 that had no outstanding invitation and now do.
        resent:
          type: array
          items:
            type: string
            format: email
          description: Addresses whose outstanding invitation was re-sent.
      required:
        - invited
        - message
        - resent
    OrganizationInvitation:
      type: object
      description: >-
        An invitation as `organization/invitations/` answers it:
        `invitations/`'s fields, plus the user

        it created (pending in the organization until they accept) and the
        workspace it was issued in

        (a workspace invitation, specs/workspaces.md §4.9a; null for an
        organization one). `created_by`,

        `user` and `workspace` are ids, each expandable. `organization_role` is
        the role in the organization

        the invitation grants, `invitations/`'s `role`.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        first_name:
          type: string
          maxLength: 150
        last_name:
          type: string
          maxLength: 150
        email:
          type: string
          format: email
          title: Email address
          maxLength: 254
        organization_role:
          allOf:
            - $ref: '#/components/schemas/OrganizationRoleEnum'
          default: member
          description: >-
            The invitee's role in the organization. Defaults to `member`. You
            cannot invite somebody to a role above your own, and on the Free
            plan only owners can be invited.


            * `owner` - Owner

            * `admin` - Admin

            * `member` - Member
        functional_area:
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/FunctionalAreaEnum'
            - $ref: '#/components/schemas/BlankEnum'
            - $ref: '#/components/schemas/NullEnum'
        other_functional_area:
          type: string
          nullable: true
          maxLength: 128
        sent_at:
          type: string
          format: date-time
          readOnly: true
        expires_at:
          type: string
          format: date-time
          readOnly: true
        accepted_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        revoked_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        created_by:
          type: integer
          readOnly: true
          description: The user who sent the invitation. (Expandable)
        user:
          type: integer
          nullable: true
          readOnly: true
          description: >-
            The user the invitation created, pending in the organization until
            they accept. (Expandable)
        workspace:
          type: string
          format: uuid
          nullable: true
          readOnly: true
          description: >-
            The workspace the invitation was issued in; null for an organization
            invitation. (Expandable)
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationInvitationWorkspace'
          writeOnly: true
          description: >-
            Workspaces to place the invitee in right away, each with their role
            there; the invitation still belongs to the organization. An owner or
            admin is an admin of every workspace: omit `workspaces` for them, or
            list every workspace as admin. No workspace twice.
      required:
        - accepted_at
        - created_at
        - created_by
        - email
        - expires_at
        - id
        - revoked_at
        - sent_at
        - user
        - workspace
    OrganizationRoleEnum:
      enum:
        - owner
        - admin
        - member
      type: string
      description: |-
        * `owner` - Owner
        * `admin` - Admin
        * `member` - Member
    FunctionalAreaEnum:
      enum:
        - data_analytics
        - sales
        - customer_support
        - operations
        - marketing
        - finance
        - product_development
        - growth
        - executive_leadership
        - other
      type: string
      description: |-
        * `data_analytics` - Data & Analytics
        * `sales` - Sales
        * `customer_support` - Customer Support
        * `operations` - Operations
        * `marketing` - Marketing
        * `finance` - Finance
        * `product_development` - Product Development
        * `growth` - Growth
        * `executive_leadership` - Executive Leadership
        * `other` - Other
    BlankEnum:
      enum:
        - ''
    NullEnum:
      enum:
        - null
    OrganizationInvitationWorkspace:
      type: object
      description: >-
        One workspace an organization invitation places its invitee in, with
        their role there.
      properties:
        workspace:
          type: string
          format: uuid
          description: A workspace of your organization.
        role:
          allOf:
            - $ref: '#/components/schemas/WorkspaceRoleEnum'
          description: |-
            The invitee's role in `workspace`.

            * `admin` - Admin
            * `member` - Member
      required:
        - role
        - workspace
    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.