API Reference
The full set of OneBusiness API endpoints, generated from the route handlers in apps/app/src/app/api/v1/. Use the operation pages in the sidebar for try-it forms and per-operation code samples.
Public REST API for OneBusiness. All routes are scoped to the authenticated party's organisation. Bearer token auth via API keys minted at /settings/api-keys.
Servers
List customers
Lists the active org's customer profiles. Each row includes the system fields plus a custom_fields map reflecting the per-tenant custom-field values. Returns up to 500 rows (no pagination in v1).
Authorizations
API key in the form one_pk_<random>. Mint at /settings/api-keys.
Parameters
Query Parameters
Filter by status. all returns every status; default is active.
"active""inactive""archived""all"Comma-separated sparse fieldset. Supports id,name,custom_fields or custom_fields.<key>. Unknown keys are dropped silently.
Responses
Array of customer-profile envelopes with total count.
Get a customer
Returns a single customer profile, honouring ?fields= selection.
Authorizations
API key in the form one_pk_<random>. Mint at /settings/api-keys.
Parameters
Path Parameters
The customer-profile id (uuid).
"123"Query Parameters
Comma-separated sparse fieldset. See list endpoint.
Responses
Successful response
Update a customer
Patches top-level fields and/or the custom_fields map. Custom-field values are validated against the active CustomFieldDefinition set — failed keys come back in rejected while siblings still apply.
Authorizations
API key in the form one_pk_<random>. Mint at /settings/api-keys.
Parameters
Path Parameters
The customer-profile id (uuid).
"123"Request Body
Responses
Successful response
List metrics
Returns the catalog of metrics visible to the caller. Capability filtering happens automatically — metrics requiring scopes the caller doesn't have are omitted.
Authorizations
API key in the form one_pk_<random>. Mint at /settings/api-keys.
Parameters
Query Parameters
Filter metrics by category. Omit to list all visible metrics.
"revenue""profitability""expenses""cash""ar""ap""tax""balance_sheet""people""growth""diversity""pay_equity""quality""vendor""customer""operations"Responses
List of metric metadata with total count and computedAt timestamp.
Describe a metric
Returns metadata for a single metric (label, description, category, unit, shape, accepted periods, required capability) without resolving a value. Useful for catalog browsing and form-building without paying resolver cost.
Authorizations
API key in the form one_pk_<random>. Mint at /settings/api-keys.
Parameters
Path Parameters
The metric id, e.g. revenue.total or cash.balance. See the metric reference for the full list.
"123"Responses
The metric's metadata wrapped in the standard envelope.
Resolve many metrics in one request
Resolves up to 50 metrics in a single request. The batch never short-circuits — each query gets its own ok/error result keyed by the caller-supplied key. Useful for dashboards that need many metrics at once.
Authorizations
API key in the form one_pk_<random>. Mint at /settings/api-keys.
Request Body
Responses
Per-key results map and shared meta envelope.
Resolve a metric value
Returns the computed value for a single metric, scoped to the period and as-of date. Capability scopes on the API key gate which metrics resolve.
Authorizations
API key in the form one_pk_<random>. Mint at /settings/api-keys.
Parameters
Path Parameters
The metric id, e.g. revenue.total or cash.balance.
"123"Query Parameters
Period to resolve. Keywords (today, mtd, ytd, last_fy, last_12_months, …) or an absolute range YYYY-MM-DD:YYYY-MM-DD. See the period syntax guide.
Pin all relative periods to this historical date (YYYY-MM-DD or today). Defaults to today.
Responses
The resolved metric value wrapped in the standard envelope. data.kind discriminates the shape (scalar, timeseries, etc.).