List users in business unit

GET

/internal/companies/{companyId}/business-units/{businessUnitId}/users

• Production
• Local development

Users with an active business_unit_memberships row for (companyId, businessUnitId). Platform staff or company MANAGER and above in companyId.

Authorizations

• bearerAuth

Parameters

Path Parameters

companyId

required

string format: uuid

businessUnitId

required

string format: uuid

Query Parameters

limit

integer

default: 50

offset

integer

0

Responses

200

User list

object

success

required

boolean

data

required

data

Array<object>

object

id

string format: uuid

email

string

fullName

string

globalRole

string

isActive

boolean

approvalStatus

string

Allowed values: PENDING APPROVED REJECTED

tokenVersion

integer

phoneNumber

string

nullable

profilePictureUrl

string

nullable

authProvider

string

createdAt

string format: date-time

updatedAt

string format: date-time

memberships

null when the user has no company membership rows; otherwise an array of company memberships with nested BU rows for that company only.

Array

nullable

object

id

string format: uuid

userId

string format: uuid

companyId

string format: uuid

role

Tenant IAM role (e.g. MANAGER company-wide; FINANCE; SUBMITTER). Distinct from BU role on businessUnitMemberships.

string

Allowed values: TENANT_SUPERADMIN ADMIN FINANCE MANAGER SUBMITTER

isActive

boolean

approvalLimit

Optional per-user-per-company approval limit (decimal string; migrated from Finance)

string

nullable

invoiceViewScope

Echoed from metadata.invoiceViewScope when set (OWN | BU | COMPANY). Company-level when user has no BU rows or as default; see README_AUTH_API.md §5.2a.

string

nullable

canEditOthersScope

Echoed from metadata.canEditOthersScope when set.

string

nullable

canEditOthersInvoices

Echoed from metadata.canEditOthersInvoices when set (legacy boolean).

boolean

nullable

metadata

Optional JSON object. Recommended keys for Finance invoice/bill visibility and editing others’ drafts — see README_AUTH_API.md (invoice scope metadata). Omitted on upsert leaves existing metadata unchanged. invoiceViewScope / canEditOthersScope / canEditOthersInvoices are also returned as top-level fields when present.

nullable

createdAt

string format: date-time

updatedAt

string format: date-time

businessUnitMemberships

Business unit memberships for this user within this company (empty key omitted).

Array<object>

object

id

string format: uuid

userId

string format: uuid

companyId

string format: uuid

businessUnitId

string format: uuid

role

BU IAM — APPROVER (manager), SUBMITTER, or BU ADMIN; combine with invoiceViewScope for bills.

string

Allowed values: SUBMITTER APPROVER ADMIN

isActive

boolean

invoiceViewScope

Echoed from metadata when set (per-BU invoice list scope).

string

nullable

canEditOthersScope

string

nullable

canEditOthersInvoices

boolean

nullable

metadata

Optional JSON object. For SUBMITTER (and product-defined cases), use invoice scope keys per README_AUTH_API.md. Finance migration may set invoiceViewScope and canEditOthersInvoices (boolean). Scope keys are also echoed as top-level fields when present.

nullable

createdAt

string format: date-time

updatedAt

string format: date-time

temp_businessUnits

BU membership rows whose company_id does not match any company_memberships row for this user (e.g. migration gaps). For repair; normal rows appear under memberships[].businessUnitMemberships.

Array<object>

object

id

string format: uuid

userId

string format: uuid

companyId

string format: uuid

businessUnitId

string format: uuid

role

BU IAM — APPROVER (manager), SUBMITTER, or BU ADMIN; combine with invoiceViewScope for bills.

string

Allowed values: SUBMITTER APPROVER ADMIN

isActive

boolean

invoiceViewScope

Echoed from metadata when set (per-BU invoice list scope).

string

nullable

canEditOthersScope

string

nullable

canEditOthersInvoices

boolean

nullable

metadata

Optional JSON object. For SUBMITTER (and product-defined cases), use invoice scope keys per README_AUTH_API.md. Finance migration may set invoiceViewScope and canEditOthersInvoices (boolean). Scope keys are also echoed as top-level fields when present.

nullable

createdAt

string format: date-time

updatedAt

string format: date-time

401

Missing/invalid token or credentials

object

success

required

boolean

error

required

object

code

required

string

Example

validation_error

message

required

string

403

Authenticated but not allowed (e.g. wrong role or invalid internal key)

object

success

required

boolean

error

required

object

code

required

string

Example

validation_error

message

required

string