/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Create Invitation

Create Invitation

Invite someone to a workspace by email.

POST/v1/orgs/{orgId}/invitesTry it
Session token

Invites an email address to the workspace and sends the invitation email. The invitee doesn't need a Syntext account yet.

The response does not include the invitation token. The token is sent only to the invited address, because holding it is how the invitee proves they own that mailbox when they accept.

Note

Requires the admin or owner role and a session JWT. API keys are rejected with 401. Any plan, but each plan caps the number of seats — see plan seat limit below — and a workspace can have at most 10 pending invitations at a time — see invite limit.

Path Parameters

NameDescription
orgId:stringpathRequired
The organization ID.

Request Body

NameDescription
email:stringbodyRequired
The address to invite.
role:stringbody
admin or member.
Default"member"
expiresInDays:numberbody
How long the invitation stays valid, 1–30 days.
Default7

Response — 201 Created

The invitation is recorded in the audit log as org.invite.created. To send the email again, use Resend Invitation.

Error Responses

400 Bad Request

validation_error — an invalid email, unknown role or out-of-range expiresInDays. details.issues lists each problem — see Validation errors.

401 Unauthorized

unauthorized for a missing, invalid or expired token (or an API key); session_revoked when the session has been signed out.

402 Payment Required

USAGE_LIMIT_EXCEEDED — the plan's seat limit is reached, and no invitation is created. Seats are current members plus invitations that can still be accepted (pending and not expired) — declined, revoked and expired invitations don't hold a seat. Free allows 2, Starter 5, Pro 20, Enterprise unlimited. Adding a member directly applies the same limit.

json
{
"error": {
"code": "USAGE_LIMIT_EXCEEDED",
"message": "Your free plan allows up to 2 team members. Upgrade to add more.",
"details": {
"limit": "members",
"max": 2,
"tier": "free",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}

403 Forbidden

forbidden — you are a member ("Only workspace admins can invite members.", with details.requiredRole: "admin" and details.currentRole), or you don't belong to the workspace ("Not a member of this organization").

404 Not Found

not_found ("Organization not found") — the workspace does not exist or has been deleted.

409 Conflict

invite_limit_reached — the workspace already has 10 pending invitations, and no invitation is created. Only invitations that can still be accepted count (pending and not expired); revoke one with Revoke Invitation, or wait for one to be accepted, declined or to expire. No plan raises this limit. When the seat limit is reached too, this error is returned rather than the 402. details.max is the limit and details.pending the current count.

json
{
"error": {
"code": "invite_limit_reached",
"message": "A workspace can have up to 10 pending invites. Revoke one, or wait for one to be accepted or expire.",
"details": {
"max": 10,
"pending": 10,
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}

To invite several people, send one request per address; each counts toward the limit as it is created.

Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/orgs/3f9c2a1e-6b4d-4e8a-a1c7-5d2e9f0b7c13/invites \
-H "Authorization: Bearer $SYNTEXT_JWT" \
-H "Content-Type: application/json" \
-d '{ "email": "alex@example.com", "role": "member" }'
Responseapplication/json
201Created
{
"data": {
"id": "9b1d3f5a-7c2e-4a6b-8d0f-1e3a5c7b9d24",
"orgId": "3f9c2a1e-6b4d-4e8a-a1c7-5d2e9f0b7c13",
"email": "alex@example.com",
"role": "member",
"status": "pending",
"expiresAt": "2026-11-15T10:00:00.000Z",
"createdAt": "2026-11-08T10:00:00.000Z",
"invitedByUserId": "0b7e4c2d-9a1f-4d3e-8c56-2f1a7b9e0d48"
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext