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

# Invite User

> Invite one person to your organization, optionally placing them in workspaces, or resend the invitation they already have.

Invites a single person to your organization. The same call also **resends** an existing invitation: posting an address that already has a live invitation resends it rather than creating a second one.

Inviting someone provisions them immediately as a **pending member** of the organization. With `workspaces`, the same call also places them in workspaces, each with a role, so you can add them to permission groups and grant them access in those workspaces before they accept. See [Pending users and pre-granted invitations](#pending-users-and-pre-granted-invitations) below.

## Request body

| Parameter | Type | Required | Description |
| - | - | - | - |
| `email` | string | Yes | The address to invite. Normalized before storing, so casing never creates a duplicate. |
| `organization_role` | string | No | The invitee's role in the organization: `owner`, `admin`, or `member`. Defaults to `member`. |
| `workspaces` | array | No | Workspaces to place the invitee in right away, each as `{"workspace": "<workspace id>", "role": "admin" \| "member"}`. No workspace can appear twice. |
| `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. |

> [!NOTE]
>
> Organization owners and admins are admins of every workspace. When `organization_role` is `owner` or `admin`, omit `workspaces`, or list every active workspace of the organization with the `admin` role. Any other list is rejected with `400` (`workspaces_inconsistent_with_role`).

The invitation belongs to the organization even when it names workspaces: it is listed and revoked through the organization's invitations.

## Response

Returns the [Organization invitation](https://docs.nekt.com/platform-api/invitations/organization/invitation.md) object. The status code tells you which of the two things happened:

* `201 Created`: a new invitation was created.
* `200 OK`: an existing invitation was resent.

The response includes `user`, the id of the pending user the invitation created. You can use it immediately as a grant or group target.

## Example

```bash theme={null}
curl --request POST \
  --url https://api.nekt.ai/api/v1/organization/invitations/ \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "email": "newcomer@example.com",
    "organization_role": "member",
    "workspaces": [
      {"workspace": "3f6c2a1e-9b4d-4c7a-8e21-5d0b7a9c4e12", "role": "member"}
    ]
  }'
```

## Resending and role changes

Sending the same address again is safe and is how you chase someone who has not accepted. Nobody is duplicated: the existing invitation is resent with a fresh expiry, and the invitee's existing groups and grants are untouched.

If `organization_role` differs from the outstanding invitation, the resend is a role **change**: it moves the person on both the invitation and their pending membership.

> [!WARNING]
>
> Moving an existing `admin` or `owner` invitee to another role requires an owner. This is the same ceiling that applies to changing the role of an accepted member.

## Pending users and pre-granted invitations

Because an invitation provisions the person right away, they exist as a pending member the moment the call succeeds:

* **Grant access before acceptance.** In every workspace the invitee was placed in, a pending member is a normal target for every permission-assign endpoint, and can be [added to a permission group](https://docs.nekt.com/platform-api/permission-groups/add-members.md) with no separate flow.
* **Pending is not inactive.** In the member list a pending member carries its own status; it is not the same as a deactivated user.
* **They cannot log in until they accept.** The invitation token is the only proof that the person controls the address.
* **Revoking is destructive.** [Revoking](https://docs.nekt.com/platform-api/invitations/organization/revoke.md) removes the invitee's workspaces, groups, and grants, not just the email.

The invitation email expires after 7 days; the pre-granted access does not. An admin resends and nothing has to be re-granted.

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

An API key belongs to one workspace, so through a key `workspaces` can only name the key's own workspace. Any other workspace is rejected with `400`.

## Errors

| Status | When |
| - | - |
| `400` | The address already belongs to an active member of the organization. |
| `400` | `email` is missing or malformed. |
| `400` | A workspace in `workspaces` is not an active workspace of your organization, is not reachable by the API key, or appears twice. |
| `400` | `workspaces_inconsistent_with_role`: the request makes the invitee an owner or admin and `workspaces` does not list every workspace as `admin`. |
| `403` | The caller is a member, or the request names an organization role above the caller's own. |
| `403` | The request changes the role of an existing `admin` or `owner` invitee and the caller is not an owner. |
| `403` | The organization is on the Free plan, where only owners may be invited. |

## Related

* [Onboarding flow](https://docs.nekt.com/platform-api/invitations/overview.md): invite, group, and grant before somebody accepts.
* [Bulk Invite Users](https://docs.nekt.com/platform-api/invitations/organization/bulk-invite.md): invite several people in one call.
* [Invite to Workspace](https://docs.nekt.com/platform-api/invitations/workspace/invite.md): invite someone into your current workspace as a workspace admin.
* [List Invitations](https://docs.nekt.com/platform-api/invitations/organization/list.md): what is still outstanding.
* [Revoke an Invitation](https://docs.nekt.com/platform-api/invitations/organization/revoke.md): and what it takes back.


## OpenAPI

````yaml POST /api/v1/organization/invitations/
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/:
    post:
      tags:
        - v1
      description: >-
        Invite one person, or resend the invitation they already have.


        `create` rather than `perform_create` because the status code depends on
        which of the two

        happened, and `perform_create` cannot influence it -- `CreateModelMixin`
        discards what it

        returns and answers 201 either way. A resend creates nothing, so it
        answers 200.
      operationId: v1_organization_invitations_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationInvitation'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OrganizationInvitation'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OrganizationInvitation'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationInvitation'
          description: ''
      security:
        - ApiKeyAuth: []
components:
  schemas:
    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.