> ## 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 to Workspace

> Add someone to your current workspace, inviting them to the organization if they are not in it yet.

Puts one person in the workspace the API key belongs to, with a workspace role. This is the endpoint for **workspace admins**: it never needs organization-level rights, and what it does depends on whether the person is already in the organization.

| The person is... | What happens | `status` | HTTP |
| - | - | - | - |
| Active in the organization | Added to this workspace at `role`. No email is sent. | `associated` | `200` |
| Pending in the organization, with an open invitation | Added to this workspace at `role`, and their invitation is resent from this workspace. | `resent` | `200` |
| Pending in the organization, with an expired invitation | Added to this workspace at `role`, and a new invitation is issued from this workspace. | `invited` | `201` |
| Not in the organization | Invited to the organization as a `member`, and placed in this workspace at `role`, pending until they accept. | `invited` | `201` |

An invitation issued here still belongs to the organization: the invitee joins the organization as a `member` and this workspace at `role`. To invite someone with a different organization role, or into several workspaces at once, use [Invite User](https://docs.nekt.com/platform-api/invitations/organization/invite.md).

## Request body

| Parameter | Type | Required | Description |
| - | - | - | - |
| `email` | string | Yes | The address to invite. |
| `role` | string | Yes | The person's role in this workspace: `admin` or `member`. |
| `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. |

## Response

| Field | Description |
| - | - |
| `status` | `invited`, `resent`, or `associated`, as in the table above. |
| `user` | The person as the workspace's user list shows them, with their `workspace_membership` and `organization_membership`. |
| `invitation` | The [workspace invitation](https://docs.nekt.com/platform-api/invitations/workspace/invitation.md) sent or resent. `null` when nothing was sent (`associated`). |

```json theme={null}
{
  "status": "invited",
  "user": {
    "id": 48,
    "first_name": "",
    "last_name": "",
    "email": "newcomer@example.com",
    "picture": "",
    "workspace_membership": {"role": "member", "is_active": true, "joined_at": null},
    "organization_membership": {"role": "member", "is_active": false, "is_pending": true, "joined_at": null}
  },
  "invitation": {
    "id": "c1f0a9d4-5b62-4e18-9a73-2d8e4f6b0c51",
    "email": "newcomer@example.com",
    "organization_role": "member",
    "workspace_role": "member",
    "shared": false,
    "user": 48,
    "created_by": 12,
    "sent_at": "2026-11-16T10:14:02Z",
    "expires_at": "2026-11-23T10:14:02Z"
  }
}
```

## Example

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

## 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. The workspace is always the key's own workspace.

Only a **workspace admin** can invite to a workspace. For an API key, that is read from the creator's role in the key's workspace. Organization owners and admins are admins of every workspace, so their keys qualify too.

> [!NOTE]
>
> On the Free plan every member of the organization is an owner, so a workspace has no `member` role: send `role: "admin"`. A new invitee joins the organization as an owner.

## Errors

| Status | When |
| - | - |
| `400` | `email` is missing or malformed, or `role` is not `admin` or `member`. |
| `400` | `already_in_workspace`: the person is already active in this workspace with another role. Change their role on the workspace's user list instead. |
| `400` | `organization_membership_inactive`: the person was deactivated in the organization. Reactivate them there first. |
| `400` | `role_not_allowed_on_free_tier`: `role` is `member` on the Free plan. |
| `403` | The key's creator is not an admin of this workspace. |

## Related

* [Bulk Invite to Workspace](https://docs.nekt.com/platform-api/invitations/workspace/bulk-invite.md): several people in one call.
* [List Workspace Invitations](https://docs.nekt.com/platform-api/invitations/workspace/list.md): who is still pending in this workspace.
* [Invite User](https://docs.nekt.com/platform-api/invitations/organization/invite.md): the organization-level invite, for organization owners and admins.


## OpenAPI

````yaml POST /api/v1/workspace/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/workspace/invitations/:
    post:
      tags:
        - v1
      description: >-
        Invite someone to your current workspace. Someone already in the
        organization, active or

        invited, is only added to the workspace at `role` (`associated`, or
        `resent` with their

        pending invitation re-sent from here); anyone else is invited to the
        organization as a member

        and waits in the workspace until they accept (`invited`, 201).
      operationId: v1_workspace_invitations_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceInvitationInput'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/WorkspaceInvitationInput'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/WorkspaceInvitationInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceInvitationResult'
          description: ''
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceInvitationResult'
          description: ''
      security:
        - ApiKeyAuth: []
components:
  schemas:
    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
    WorkspaceInvitationResult:
      type: object
      description: What inviting someone to your current workspace did.
      properties:
        status:
          allOf:
            - $ref: '#/components/schemas/WorkspaceInvitationResultStatusEnum'
          description: >-
            `invited`: invited to the organization from this workspace, waiting
            in it until they accept. `resent`: already invited, their pending
            invitation was re-sent from this workspace. `associated`: already
            active in the organization, only added to this workspace; nothing
            was sent.


            * `invited` - invited

            * `resent` - resent

            * `associated` - associated
        user:
          allOf:
            - $ref: '#/components/schemas/WorkspaceUser'
          description: The person, as the workspace's users list them.
        invitation:
          allOf:
            - $ref: '#/components/schemas/WorkspaceInvitation'
          nullable: true
          description: The invitation sent or re-sent; null when nothing was sent.
      required:
        - invitation
        - status
        - user
    WorkspaceRoleEnum:
      enum:
        - admin
        - member
      type: string
      description: |-
        * `admin` - Admin
        * `member` - Member
    WorkspaceInvitationResultStatusEnum:
      enum:
        - invited
        - resent
        - associated
      type: string
      description: |-
        * `invited` - invited
        * `resent` - resent
        * `associated` - associated
    WorkspaceUser:
      type: object
      description: >-
        A user in a workspace, with their membership in the workspace and in its
        organization. The

        includable fields are the user's MFA, and their groups and grants in
        this workspace.
      properties:
        id:
          type: integer
          readOnly: true
        first_name:
          type: string
          readOnly: true
        last_name:
          type: string
          readOnly: true
        email:
          type: string
          format: email
          readOnly: true
        picture:
          type: string
          format: uri
          readOnly: true
        workspace_membership:
          allOf:
            - $ref: '#/components/schemas/WorkspaceUserWorkspaceMembership'
          readOnly: true
        organization_membership:
          allOf:
            - $ref: '#/components/schemas/WorkspaceUserOrganizationMembership'
          readOnly: true
      required:
        - email
        - first_name
        - id
        - last_name
        - organization_membership
        - picture
        - workspace_membership
    WorkspaceInvitation:
      type: object
      description: >-
        A pending invitation to the organization whose invitee already has a
        place in your current

        workspace. `organization_role` is the role in the organization the
        invitation grants, and

        `workspace_role` the role waiting for the invitee in this workspace.
        `created_by` and `user` are

        ids, each expandable.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        first_name:
          type: string
          readOnly: true
        last_name:
          type: string
          readOnly: true
        email:
          type: string
          format: email
          readOnly: true
          title: Email address
        organization_role:
          type: string
          readOnly: true
          description: The invitee's role in the organization.
        functional_area:
          readOnly: true
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/FunctionalAreaEnum'
            - $ref: '#/components/schemas/NullEnum'
        other_functional_area:
          type: string
          readOnly: true
          nullable: true
        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_role:
          type: string
          readOnly: true
          description: The role waiting for the invitee in this workspace.
        shared:
          type: boolean
          readOnly: true
          description: >-
            Whether the invitation reaches beyond this workspace: issued
            elsewhere, or its invitee is in another workspace too. A shared
            invitation is revoked from the organization's invitations, not here.
      required:
        - accepted_at
        - created_at
        - created_by
        - email
        - expires_at
        - first_name
        - functional_area
        - id
        - last_name
        - organization_role
        - other_functional_area
        - revoked_at
        - sent_at
        - shared
        - user
        - workspace_role
    WorkspaceUserWorkspaceMembership:
      type: object
      description: The user's membership in the workspace.
      properties:
        role:
          allOf:
            - $ref: '#/components/schemas/WorkspaceRoleEnum'
          readOnly: true
        is_active:
          type: boolean
          readOnly: true
          title: Active
        joined_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: >-
            When the user joined the workspace: when this membership was created
            for someone already in the organization, or when an invitee
            accepted. Empty while they are pending.
      required:
        - is_active
        - joined_at
        - role
    WorkspaceUserOrganizationMembership:
      type: object
      description: >-
        The user's membership in the workspace's organization. An active owner
        or admin of the

        organization is an admin of every workspace, so their role and status in
        a workspace cannot be

        changed.
      properties:
        role:
          allOf:
            - $ref: '#/components/schemas/OrganizationRoleEnum'
          readOnly: true
        is_active:
          type: boolean
          readOnly: true
          title: Active
        is_pending:
          type: boolean
          readOnly: true
          description: Invited to the organization and not accepted yet.
        joined_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: >-
            When the user joined the organization: when this membership was
            created for someone not invited, or when an invitee accepted. Empty
            while they are pending.
      required:
        - is_active
        - is_pending
        - joined_at
        - role
    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
    NullEnum:
      enum:
        - null
    OrganizationRoleEnum:
      enum:
        - owner
        - admin
        - member
      type: string
      description: |-
        * `owner` - Owner
        * `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.