Invite Team Member
Invite someone to join a workspace by email, with a given role.
Who can invite
Your role must have both the team:add_member and workspace:edit permissions. For a client workspace under an agency or Studio master, you also need agency_hub:manage_clients on the master workspace.
Path Parameters
workspaceIdstringrequiredThe _id of the workspace to invite the person to.
Headers
x-workspace-idstringrequiredA workspace where your role has the permissions above. Permissions are checked against this header, so it's normally the same workspace as workspaceId.
Request Body
emailstringrequiredThe email address of the person to invite. Stored in lowercase.
rolestringrequiredThe name of the role to give them. It is matched exactly, and is case-sensitive. Use a built-in role (admin, editor, viewer, all lowercase) or the name of a custom role in this workspace (see List Roles). owner is not allowed.
isSMBbooleanAgency and Studio plans only: invite the person as a simplified (SMB) client user. Defaults to true on those plans. Sending true on any other plan returns 403.
What happens
- An invitation is created that expires after 7 days.
- An email is sent to the invitee with a link to accept. The inviter's email and the workspace name are included.
- If the workspace is white-labelled (agency mode), the email is sent from the workspace's verified custom email when one is set, and the link uses the white-label domain. Otherwise the link is built from the request's
Origin(orReferer) header, falling back to the default portal URL.
Response Fields
successbooleantrue when the invitation was sent.
messagestringInvitation sent successfully.
Errors
| Status | Body | When |
|---|---|---|
400 | {"error": "An invitation has already been sent to this email."} | A pending, unexpired invitation to this email already exists for the workspace |
403 | {"error": "Cannot invite as owner"} | role is owner |
403 | {"error": "Insufficient permissions", ...} | Your role lacks team:add_member or workspace:edit |
403 | {"error": "Insufficient permissions to invite members"} | Client workspace and you lack agency_hub:manage_clients on the master |
403 | {"error": "Only Agency and Studio plans can invite SMB users."} | isSMB: true on another plan |
404 | {"error": "Workspace not found"} | No workspace with that ID that you can see |
500 | {"error": "..."} | Unexpected server error |
{
"email": "jane@company.com",
"role": "editor"
}{
"success": true,
"message": "Invitation sent successfully."
}Last updated on