Skip to main content
POST
Send a team invite

Authorizations

Authorization
string
header
required

OAuth 2.1 authorization code + PKCE (S256). Tokens are tenant-bound (company_id) and scoped. Discover endpoints via /.well-known/oauth-authorization-server.

Body

application/json

Create a team invitation. companyId is injected from the token tenant and must NOT be supplied. Required (validated in the use-case): email, code. Source: lib/api/team/create-invite.usecase.ts + lib/mcp/tools/team.ts create_team_invite call.body. The route zod (CreateInviteInput) is .passthrough().

email
string<email>
required

Email address to invite.

code
string
required

Unique invite code used for tracking / the accept link.

Minimum string length: 1
role
enum<string>

Role to grant (defaults to Employee). Granting Admin forces full permissions.

Available options:
Owner,
Admin,
Employee
permissions
object

Per-member permission flags (9-key boolean set). Each key defaults to true when omitted. Source: lib/team-permissions.ts TEAM_PERMISSION_KEYS + normalizeTeamPermissions (always returns all 9 keys).

emailPreferences
object

Per-member email-notification preferences. Source: lib/team-email-preferences.ts TEAM_EMAIL_PREFERENCE_KEYS + normalizeTeamEmailPreferences (always returns the closed key set).

propagateToAgency
boolean

Propagate the grant to all agency companies (default false; may be downgraded to false for subaccount-only inviters).

subaccountOnly
boolean

Restrict access to this subaccount only (default false).

inviterId
string

User id recorded as the inviter (defaults to the caller's user id).

Response

Result of creating a team invite: a new pending invite (inviteId + invite), or a message when an existing user was auto-added / already a member.

data
object
required

Create-invite result. Source: createTeamInvite use-case (lib/api/team/create-invite.usecase.ts). Three success shapes share { success:true }: (a) already-a-member { message }, (b) existing-user-auto-added { message }, (c) new pending invite { inviteId, invite }.