Create Invite

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

POST /api/v1/invites

cURL

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": "[e-mail]",
    "predefined_roles": ["full_user"]
  }'

Response

{
  "id": "df242ffe-393a-4615-9164-019b295c9641",
  "email": "[e-mail]",
  "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"
}

Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.

Creates an invite 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 rather than creating a second invite. To cancel it, use 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. Needs a plan that includes custom roles.

Response

Returns 201 with the new invite, 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 to email it again.

cURL

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": "[e-mail]",
    "predefined_roles": ["full_user"]
  }'

Response

{
  "id": "df242ffe-393a-4615-9164-019b295c9641",
  "email": "[e-mail]",
  "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.