Member ManagementAPI ReferenceAdd Members

Add Members (Pre-add)

POST/openapi/v1/members/add

Pre-add users to a Space as pending-activation members and send them an invitation email. This is used in Designated Space Mode before initiating OAuth authorization.

How it works: 1. Call this endpoint to pre-add the target users (status: pending activation). An invitation email is sent to each user. 2. Initiate OAuth authorization with both space_id and login_hint (see Authorization Endpoint). 3. When the user logs in on the Consent page and clicks Agree, their membership is automatically activated.

If you skip this step: Users cannot enter the designated Space through the OAuth Consent page — authorization will be rejected with access_denied.

Idempotent: If the email is already a pending-activation or active member of the Space, the call succeeds without creating duplicates or re-sending invitation emails.

Required Scope: member:manage


Request Parameters

AuthorizationRequiredstring
Bearer <access_token>
X-Operator-User-IdOptionalstring
Operator user ID. Not required in authorization_code mode (uses authorized user automatically); optional in client_credentials mode, falls back to system user ID if omitted.
application/json
SpaceIdRequiredstring
The target Space ID. The app must be installed (active) in this Space.
MembersRequiredarray<object>
List of members to add. Each member will be created with status pending-activation and sent an invitation email.
Sub-properties
EmailRequiredstring
Member email address.
NameRequiredstring
Member display name, shown in invitation emails.
RolesOptionalarray<string>
Role list. Supported values: `admin` (can manage the Space), `sender` (can create and send envelopes). If omitted, defaults to `["sender"]`.

Response Parameters

SuccessListOptionalarray<object>
Members successfully added (or already existing — idempotent).
Sub-properties
EmailOptionalstring
Member email address.
NameOptionalstring
Member display name.
StatusOptionalstring
`success` or `failed`.
successfailed
MessageOptionalstring
Failure reason (only present when Status is `failed`).
FailListOptionalarray<object>
Members that failed to be added, with reasons.
Sub-properties
EmailOptionalstring
Member email address.
NameOptionalstring
Member display name.
StatusOptionalstring
`success` or `failed`.
successfailed
MessageOptionalstring
Failure reason (only present when Status is `failed`).

Error Codes

Error CodeDescription
INVALID_REQUESTMissing or invalid parameters
UNAUTHORIZEDaccess_token missing, invalid, or expired
FORBIDDENThe app is not installed in the target Space
INTERNAL_ERRORInternal server error