Skip to content
Crossmart Docs

Invite someone by email

POST
/api/v1/workspaces/{workspaceId}/invitations
curl --request POST \
  --url https://api.crossmart.io/api/v1/workspaces/example/invitations \
  --header 'Content-Type: application/json' \
  --data '{ "role": "OWNER", "customRoleId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "email": "dana@example.com" }'

Emails a link that works for 7 days. A new invitation to the same address replaces the pending one. Refused (409) for members and past 50 pending invitations, and (402) when the plan has no seat for someone new to the organization.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
workspaceId
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
role
required

At most your own access. CUSTOM needs customRoleId.

string
Allowed values: OWNER ADMIN EDITOR APPROVER VIEWER CUSTOM
customRoleId

One of the workspace’s roles, with CUSTOM

string format: uuid
email
required
string
<= 254 characters

Example 

dana@example.com

Responses

Section titled “Responses”

201

Section titled “201”
Media typeapplication/json
object
id
required
string format: uuid
email
required
string
role
required
string
Allowed values: OWNER ADMIN EDITOR APPROVER VIEWER CUSTOM
customRole
required

The workspace’s own role, when role is CUSTOM

object
id
required
string format: uuid
name
required
string
invitedByName
required
string
expiresAt
required
string format: date-time
createdAt
required
string format: date-time

Example 

{
  "role": "OWNER"
}

402

Section titled “402”

The organization’s plan does not allow this (ENTITLEMENTS_ENFORCED is on). code and feature say why; upgrading the plan resolves it.

Media typeapplication/json
object
statusCode
required
number
error
required
string
code
required
string
Allowed values: plan_limit_reached plan_feature_not_included
message
required
string
feature
required
string
Allowed values: active_listings channel_connections workspaces members api_keys ai_credits autonomous_agents bring_your_own_key
plan
required

The code of the organization’s plan

string
limit
required

Null is unlimited

number
nullable
usage
required
number
requested
required

How many more the request asked for

number

Example 

{
  "statusCode": 402,
  "error": "Payment Required",
  "code": "plan_limit_reached",
  "message": "The Free plan includes 2 connected channels, and 2 are in use. Upgrade the plan to add more.",
  "feature": "active_listings",
  "plan": "free"
}