Create Invitation

POST/web/v1/workspaces/{workspaceBizId}/invitations JWT

Creates a new invitation to join the workspace. The invitee receives a notification and can accept or decline.

Required Headers

Header	Example Value	Description
Content-Type	application/json	Request content type
Accept	application/json	Expected response type
X-Client-Hash		Client device fingerprint
Accept-Language	en, zh, zh-Hant, ja, vi	Response language (default: en)
Authorization	Bearer	JWT access token
X-Workspace-Id		Target workspace ID

Request Parameters

Name	Type	Required	In	Description
workspaceBizId	String	Required	path	Business ID of the workspace

Request Body

{
  "inviteeEmail": "invitee@example.com",
  "message": "Welcome to our workspace",
  "expirationDays": 7
}

Request Example

{
  "inviteeEmail": "newuser@example.com",
  "message": "Welcome to our team",
  "expirationDays": 7
}

Success Response

Status: 201 Created

201 Created 201

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2001",
  "message": "CREATED",
  "data": {
    "bizId": "inv_abc123def456",
    "workspaceBizId": "WS_INVITE_TEST_001",
    "workspaceName": "Test Workspace",
    "inviterBizId": "ACC_OWNER_INVITE_001",
    "inviterName": "Owner User",
    "inviteeEmail": "invitee@example.com",
    "inviteeAccountBizId": "ACC_INVITEE_001",
    "inviteeAccountName": null,
    "invitationStatus": {
      "value": 10011001,
      "name": "PENDING",
      "code": "PENDING"
    },
    "message": "Welcome to our workspace",
    "expiresAt": "2026-03-29T10:30:00Z",
    "acceptedAt": null,
    "createdAt": "2026-03-22T10:30:00Z",
    "canAccept": true
  }
}

Response Fields

Field	Type	Description
bizId	String	Unique invitation business ID
workspaceBizId	String	Target workspace business ID
workspaceName	String	Target workspace display name
inviterBizId	String	Inviter's account business ID
inviterName	String	Inviter's display name
inviteeEmail	String	Invitee's email address
inviteeAccountBizId	String	Invitee's account ID (if registered)
inviteeAccountName	String	Invitee's display name (nullable)
invitationStatus	Object	Status enum: PENDING, ACCEPTED, CANCELLED, DECLINED, EXPIRED
message	String	Invitation message
expiresAt	String	ISO 8601 expiration timestamp
acceptedAt	String	ISO 8601 acceptance timestamp (nullable)
createdAt	String	ISO 8601 creation timestamp
canAccept	Boolean	Whether the invitation can still be accepted

Error Responses

Unauthorized 401

{
  "success": false,
  "code": "4010",
  "message": "Invalid or expired token"
}

Conflict 409

{
  "success": false,
  "code": "WORKSPACE.DUPLICATE_PENDING_INVITATION",
  "message": "A pending invitation already exists for this email"
}

Notes

• Returns HTTP 201 with response code "2001" on success.
• expirationDays defaults to 7 if omitted.
• Duplicate pending invitations for the same email return 409 WORKSPACE.DUPLICATE_PENDING_INVITATION.
• Requires workspace:invitation:write permission.