Skip to main content
POST
/
api
/
public
/
capacity
/
bulk-allocate
curl -X POST "https://app.crovver.com/api/public/capacity/bulk-allocate" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "requestingEntityId": "workspace_123",
    "users": [
      { "externalUserId": "user_1", "email": "alice@acme.com", "name": "Alice" },
      { "externalUserId": "user_2", "email": "bob@acme.com",   "name": "Bob"   },
      { "externalUserId": "user_3", "email": "carol@acme.com", "name": "Carol" }
    ],
    "metadata": { "addedBy": "admin_789" }
  }'

{
  "success": true,
  "data": {
    "allocated": ["user_1", "user_2", "user_3"],
    "skipped": [],
    "rejected": [],
    "capacity": {
      "activeCount": 8,
      "capacityUnits": 10
    }
  }
}
Inserts multiple seat allocations in a single call, up to the subscription’s current capacity_units. No proration is triggered — if the batch would exceed capacity, users are split into allocated and rejected lists. Upgrade capacity first via Proration Checkout, then retry the rejected IDs. Already-active users are silently skipped and returned in skipped — the call is safe to retry.
This endpoint is never retried automatically by the SDK to prevent duplicate allocations on network errors. Implement your own retry logic using the skipped list for idempotency.

​
Request Body

​
requestingEntityId
string
required
The external tenant ID from your application.
​
users
BulkAllocateSeatUser[]
required
List of users to allocate. Maximum 100 users per request. Each entry must have a unique externalUserId — duplicates within the same batch are rejected.
​
users[].externalUserId
string
required
Your application’s user ID. Must be non-empty and unique within the batch.
​
users[].email
string
User’s email address (stored for audit and display purposes).
​
users[].name
string
User’s display name.
​
metadata
object
Arbitrary key-value pairs attached to every allocation created in this batch.

​
Authentication

Requires a secret key (Authorization: Bearer sk_live_...) or service key (x-service-key).

​
Response

Returns HTTP 200 when all users were allocated or skipped. Returns HTTP 207 Multi-Status when at least one user was rejected due to capacity limits.
FieldTypeDescription
allocatedstring[]externalUserId values inserted this call
skippedstring[]Already active — not re-inserted
rejectedstring[]Would exceed capacity_units — not inserted
capacity.activeCountnumberActive seat count after this operation
capacity.capacityUnitsnumberTotal seat limit on the subscription
messagestringPresent when users were rejected — explains the limit
curl -X POST "https://app.crovver.com/api/public/capacity/bulk-allocate" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "requestingEntityId": "workspace_123",
    "users": [
      { "externalUserId": "user_1", "email": "alice@acme.com", "name": "Alice" },
      { "externalUserId": "user_2", "email": "bob@acme.com",   "name": "Bob"   },
      { "externalUserId": "user_3", "email": "carol@acme.com", "name": "Carol" }
    ],
    "metadata": { "addedBy": "admin_789" }
  }'

{
  "success": true,
  "data": {
    "allocated": ["user_1", "user_2", "user_3"],
    "skipped": [],
    "rejected": [],
    "capacity": {
      "activeCount": 8,
      "capacityUnits": 10
    }
  }
}