Bulk User Invitation
Legacy Endpoints (Deprecated)
Bulk User Invitation
Invite multiple users to your organization at once with smart handling for existing users
POST
Bulk User Invitation
This endpoint requires organization admin privileges. Only users with the
org:admin role can bulk invite users to their organization.Smart User Handling: This endpoint automatically detects existing users and handles them appropriately:
- New users: Sends email invitations
- Existing users: Adds them directly as organization members
- Already members: Reports their current status without errors
Authentication
string
required
Bearer token for authentication. Must be from a user with
org:admin role.Body
array
required
Array of invitation objects (1-50 invitations per request)
Response
boolean
Whether all invitations were successfully created
number
Total number of invitations requested
number
Number of invitations successfully created
number
Number of invitations that failed to create
array
Array of successful invitation results
array
Array of failed invitations (only present if there were failures)
Examples
Error Codes
object
Bad Request - Invalid request data or validation errors
object
Unauthorized - Invalid or missing authentication
object
Forbidden - User is not an admin in the organization
object
Method Not Allowed - Only POST requests are accepted
object
Multi-Status - Some invitations succeeded, others failed (partial success)
Features
Smart User Detection: Automatically handles different user scenarios without requiring you to know their status beforehand.- New Users: Automatically sends email invitations with 30-day expiration
- Existing Users: Adds them directly as organization members (no email needed)
- Current Members: Gracefully reports their existing status without errors
- Re-invitations: Previously removed users can be seamlessly re-added
- Mixed Batches: Process new and existing users in the same request
- Zero Errors: No “user already exists” failures - all scenarios handled intelligently
Metadata
You can set organization-scoped user metadata during invitation:- User roles (
role: "manager") - Department info (
department: "engineering") - Team assignments (
team: "backend") - Custom properties (any key-value pairs)
Limits
- Batch Size: 1-50 invitations per request
- Email Validation: All email addresses must be valid
- Rate Limiting: Subject to Clerk’s API rate limits
- Expiration: Invitations expire after 30 days