POST
/
admin
/
bulkInvite
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,
      "invitation_id": "<string>",
      "status": "<string>",
      "expires_at": "<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.

​
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

Simple & Clean: Just provide emails and metadata - we handle all the Clerk complexity for you.

  • Email Notifications: Always sent automatically
  • Existing Users: Won’t cause errors (re-invitations work)
  • Expiration: Standard 30-day expiration
  • Redirect: Users go to your app’s default sign-up flow

​
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