POST
/
admin
/
bulkInvite
Bulk User Invitation
curl --request POST \
  --url https://asteragents.com/api/admin/bulkInvite \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "invitations": [
    {
      "email": "<string>",
      "metadata": {}
    }
  ]
}'
{
  "207": {},
  "400": {},
  "401": {},
  "403": {},
  "405": {},
  "success": true,
  "total": 123,
  "successful": 123,
  "failed": 123,
  "results": [
    {
      "email": "<string>",
      "success": true,
      "type": "<string>",
      "status": "<string>",
      "invitation_id": "<string>",
      "user_id": "<string>",
      "membership_id": "<string>",
      "expires_at": "<string>",
      "role": "<string>",
      "metadata": {}
    }
  ],
  "errors": [
    {
      "email": "<string>",
      "success": true,
      "error": "<string>"
    }
  ]
}
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

​
Authorization
string
required
Bearer token for authentication. Must be from a user with org:admin role.

​
Body

​
invitations
array
required
Array of invitation objects (1-50 invitations per request)

​
Response

​
success
boolean
Whether all invitations were successfully created
​
total
number
Total number of invitations requested
​
successful
number
Number of invitations successfully created
​
failed
number
Number of invitations that failed to create
​
results
array
Array of successful invitation results
​
errors
array
Array of failed invitations (only present if there were failures)

​
Examples

curl -X POST https://asteragents.com/api/admin/bulkInvite \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "invitations": [
      {
        "email": "john@company.com"
      },
      {
        "email": "sarah@company.com"
      }
    ]
  }'

​
Error Codes

​
400
object
Bad Request - Invalid request data or validation errors
​
401
object
Unauthorized - Invalid or missing authentication
​
403
object
Forbidden - User is not an admin in the organization
​
405
object
Method Not Allowed - Only POST requests are accepted
​
207
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 user metadata during invitation:
  • User roles (role: "manager")
  • Department info (department: "engineering")
  • Team assignments (team: "backend")
  • Custom properties (any key-value pairs)
Metadata is stored as publicMetadata in Clerk and becomes accessible to both frontend and backend after user signs up.
For sensitive data that should only be server-accessible, set it after signup using Clerk webhooks.

​
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