Bulk assign users to an organization
const url = 'https://apisandbox.puurk.com/bulk/example/users';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"role":"owner","uids":["example"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://apisandbox.puurk.com/bulk/example/users \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "role": "owner", "uids": [ "example" ] }'Grant several users the same role in one organization in one call. Every target is a role modification. Setting a role requires one of: an organization role of owner or agencyadmin in this organization; a superadmin claim; or a service token holding the admin scope action on organizations (globally or for this organization). admin is a scope action, not an organization role, and is rejected as a role value with 400. A request that includes the caller’s own uid is refused as a whole with 403. A per-user failure — removing the organization’s last owner — is reported in results with status: error, not as an error status, so the other users are still written.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Organization ID
Request Bodyrequired
Section titled “Request Bodyrequired”Request body
Body for POST /bulk/{oid}/users.
object
Role of a user in an organization, as stored in the organization’s roles map. admin is not a role: it is a service-token scope action, and a request that sends it as a role gets 400. Of the organization roles, only owner and agencyadmin may change other members’ roles.
User ids to grant role to.
Responses
Section titled “Responses”One result per requested uid, in request order. Check each status; a 200 does not mean every user was written.
object
object
Outcome for one target of a bulk assignment.
Present when status is error: Cannot remove the last owner of an organization, or Failed to assign user (the write for this user failed).
Example
{ "results": [ { "status": "success" } ]}bad_request — Missing or invalid required field: role (absent, or not an OrganizationRole; admin is a scope action, not a role) or Missing or empty required field: uids.
The standard error body. error is a stable, machine-readable code — branch on it rather than on message, which is for humans and may change.
object
Machine-readable error code.
Human-readable detail.
Example
{ "error": "merchant_account_missing", "message": "The organization has no merchant account. Complete Stripe Connect onboarding for this organization before generating pricing."}Unauthorized
forbidden — the caller lacks the write action on organizations for this organization, uids includes the caller’s own uid (Cannot modify your own role), or the caller holds none of: an organization role of owner or agencyadmin, a superadmin claim, or a service token with the admin scope action on organizations. Nothing is written.
The standard error body. error is a stable, machine-readable code — branch on it rather than on message, which is for humans and may change.
object
Machine-readable error code.
Human-readable detail.
Example
{ "error": "merchant_account_missing", "message": "The organization has no merchant account. Complete Stripe Connect onboarding for this organization before generating pricing."}not_found — the organization does not exist.
The standard error body. error is a stable, machine-readable code — branch on it rather than on message, which is for humans and may change.
object
Machine-readable error code.
Human-readable detail.
Example
{ "error": "merchant_account_missing", "message": "The organization has no merchant account. Complete Stripe Connect onboarding for this organization before generating pricing."}