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

# Create Invite

> Invite someone to join your organisation by email, with the roles they get on joining.

> [!NOTE]
>
> **Preview.** This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive `403 mcp_not_enabled`. See the [preview overview](/preview).

Creates an [invite](/proposed/objects#organisation) and emails the join link to `email`. When the invitee accepts, they become a member with the roles you set.

The invite lasts 30 days. If the email goes astray, use [Resend Invite](/api-reference/organisation/resend-invite) rather than creating a second invite. To cancel it, use [Revoke Invite](/api-reference/organisation/revoke-invite).

The response never includes the join link. Wordsmith only sends it to the invitee's inbox.

## Authentication

Requires an API key, or an OAuth token with `directory:admin`. The caller must also be an organisation admin, or hold a role with the matching permission. `directory:admin` is never granted by default. It only narrows what the person who approved it can already do, so a team admin's token can edit their own teams and nothing else. Admin changes are not available through the MCP server.

Giving the invitee a custom role also needs the permission to assign roles.

## Body parameters

**email** `string` *required*

The invitee's email address.

**predefined\_roles** `string[]`

Built-in roles for the invitee: any of `viewer`, `full_user` and `admin`. If you send neither `predefined_roles` nor `custom_role_ids`, your organisation's default roles for new members apply. That default is `["full_user"]` unless an admin changed it in Settings.

**custom\_role\_ids** `string[]`

Custom roles for the invitee, from [List Roles](/api-reference/organisation/list-roles). Needs a plan that includes custom roles.

## Response

Returns `201` with the new [invite](/proposed/objects#organisation), with `status` set to `pending`.

If this email already has a pending invite, Wordsmith sends nothing and returns `200` with that invite, unchanged. Use [Resend Invite](/api-reference/organisation/resend-invite) to email it again.

```bash cURL theme={null}
curl -X POST "https://api.wordsmith.ai/api/v1/invites" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dana.okafor@example.com",
    "predefined_roles": ["full_user"]
  }'
```

```json Response theme={null}
{
  "id": "df242ffe-393a-4615-9164-019b295c9641",
  "email": "dana.okafor@example.com",
  "predefined_roles": ["full_user"],
  "custom_role_ids": [],
  "status": "pending",
  "invited_by": "4c98ef69-d5ef-4471-a2b8-89ded5b7b121",
  "created_at": "2026-10-13T09:30:00Z",
  "expires_at": "2026-11-12T09:30:00Z"
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | `email` is missing or not a valid address, a `predefined_roles` value is not `viewer`, `full_user` or `admin`, or a `custom_role_ids` value is not a role id. |
| 400 | `bad_request` | A predefined role is turned off for your organisation, or a custom role is inactive or does not exist. The message names it. |
| 403 | `insufficient_scope` | The OAuth token does not hold `directory:admin`. |
| 403 | `forbidden` | The caller cannot invite members. Also returned for `custom_role_ids` when the caller cannot assign roles or the plan has no custom roles. |
| 409 | `user_invite_user_exists` | Someone with this email is already a member. Change their roles with [Update Member](/api-reference/organisation/update-member). |


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