Skip to main content
POST
/
admin
/
bulkInvite
Bulk User Invitation
curl --request POST \
  --url https://asteragents.com/api/admin/bulkInvite \
  --header 'Authorization: <authorization>' \
  --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>"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt

Use this file to discover all available pages before exploring further.

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 organization-scoped user metadata during invitation:
  • User roles (role: "manager")
  • Department info (department: "engineering")
  • Team assignments (team: "backend")
  • Custom properties (any key-value pairs)
Organization Isolation: Metadata is scoped to your organization. If a user joins multiple organizations, each org maintains separate metadata for that user. Metadata becomes accessible to both frontend and backend after user signs up and can be updated later via the Update User Metadata endpoint.
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