Add a user to an organization
const url = 'https://apisandbox.puurk.com/organizations/example/user/example';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"status":"active","start_date":"2026-04-15T12:00:00Z","termination_date":"2026-04-15T12:00:00Z","commission_basis":"profit","commission_fixed":1,"commission_rate":1,"commission_trigger":"sale","role":"owner"}'};
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/organizations/example/user/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "status": "active", "start_date": "2026-04-15T12:00:00Z", "termination_date": "2026-04-15T12:00:00Z", "commission_basis": "profit", "commission_fixed": 1, "commission_rate": 1, "commission_trigger": "sale", "role": "owner" }'Add or set a user’s membership and role in an organization. This writes the organization’s roles map as well as the user record, so it is always 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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Organization ID
User ID
Request Bodyrequired
Section titled “Request Bodyrequired”Request body
Body for POST /organizations/{oid}/user/{uid} and PATCH /organizations/{oid}/user/{uid}. Every field is optional. On POST, role defaults to read; on PATCH, omitting role leaves it unchanged.
object
Membership status.
When the person started with this organization. ISO 8601, or null to clear.
When the person left. ISO 8601, or null to clear.
Fixed commission amount in cents
Commission rate
The role to grant. 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.
Responses
Section titled “Responses”User added. The body is the organization user record plus the resolved role.
An organization user record with its role from the organization’s roles map. role is null for an orphaned record — one that exists in the users subcollection with no entry in roles.
object
Organization user document ID
User ID
Organization ID
Fixed commission amount in cents
Commission rate
Example
{ "status": "active", "commission_basis": "profit", "commission_trigger": "sale", "role": "owner"}bad_request — invalid body or date field, or role is not an OrganizationRole (Invalid role. Must be one of: owner, manager, read, write, provider, accountant, officeadmin, agencyadmin, agencyuser, none). admin is rejected here: it is a scope action, not a role.
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 may not set this user’s role. Either the caller is the target user, 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 created.
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."}conflict — this would remove the organization’s last owner.
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."}