Practice Manager API

Budgets

Budgets let partners create workspace financial plans with versioned cell grids. Partner responses expose budget UUIDs as `id`, strip internal numeric foreign keys, and require `accountUuid` (not numeric `accountId`) on cell update payloads.

Last updated 2026-11-18

Overview

The Budgets API lets your integration list, create, update, publish, archive, and duplicate budgets in a workspace. Each budget carries metadata (name, cadence, period counts, currency) and one or more numbered versions with a cell grid keyed by chart-of-accounts UUIDs.

Cell updates accept `accountUuid` and reject bare numeric `accountId` fields. Use `GET /firm-partners/workspace/budgets/{uuid}/grid` to read the grid with optional actuals, then patch individual cells or bulk-import many rows at once.

Key concepts

Overall Budget

Each workspace may have at most one Overall Budget (`isOverall: true`). Fetch it with `GET /firm-partners/workspace/budgets/overall` or create it explicitly on `POST /firm-partners/workspace/budgets`.

Versions and the grid

New budgets receive version 1 automatically. Create additional versions with `POST /firm-partners/workspace/budgets/{uuid}/versions`, then read or update cells against a specific `versionNumber`.

Account UUIDs on cells

Cell update bodies must use `accountUuid` from the chart of accounts. Sending numeric `accountId` without `accountUuid` returns 400.

Publish and archive

Publishing locks a version snapshot. Archived budgets are excluded from name-uniqueness checks and can be recreated under the same name.

The budget object

Metadata returned on budget list and detail responses. Nested `versions` omit internal database ids.

Attributes

iduuid

Budget identifier (UUID). Use in path parameters.

namestring

Display name. Must be unique among non-archived budgets in the workspace.

startPerioddate

First budget period start date (ISO date).

cadenceenum

Period cadence.

One of: monthly, yearly

actualPeriodsinteger

Number of historical actual periods included.

budgetPeriodsinteger

Number of forward budget periods (minimum 1).

currencyCodestring

ISO 4217 currency code.

statusenum

Budget lifecycle status.

One of: draft, published, archived

lockedAtdatetime

When the budget was locked, or null.

isOverallboolean

Whether this is the workspace Overall Budget (at most one per workspace).

versionsarray

Version summaries attached to the budget.

versionNumberinteger

1-based version number used in path parameters.

labelstring

Human-readable version label.

isPublishedboolean

Whether this version is the published snapshot.

createdAtdatetime

When the version was created.

createdAtdatetime

ISO 8601 creation timestamp.

updatedAtdatetime

ISO 8601 last update timestamp.

Example
{
  "id": "55667788-99aa-bbcc-ddee-ff0011223344",
  "name": "FY 2026 Operating Budget",
  "startPeriod": "2026-01-01",
  "cadence": "monthly",
  "actualPeriods": 3,
  "budgetPeriods": 12,
  "currencyCode": "USD",
  "status": "draft",
  "lockedAt": null,
  "isOverall": false,
  "versions": [
    {
      "versionNumber": 1,
      "label": "Initial",
      "isPublished": false,
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  ],
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-28T14:22:30.000Z"
}

Grid actuals

Pass `includeActuals=false` on the grid route to omit actual-period columns. `reportType` accepts `accrual` (default) or `cash`.

Published budgets

Metadata updates are rejected when `status` is `published` or `lockedAt` is set. Duplicate or create a new version instead.

Endpoints

GET
Get overall budget/firm-partners/workspace/budgets/overall

Returns the workspace Overall Budget, if one exists.

GET
List budgets/firm-partners/workspace/budgets

Returns all budgets in the workspace, optionally filtered by status.

POST
Create budget/firm-partners/workspace/budgets

Creates a budget and its initial version.

GET
Get budget/firm-partners/workspace/budgets/{uuid}

Retrieves a single budget by UUID.

PATCH
Update budget metadata/firm-partners/workspace/budgets/{uuid}

Updates budget metadata. Rejected when the budget is published or locked.

DELETE
Delete budget/firm-partners/workspace/budgets/{uuid}

Deletes a draft budget.

GET
Get budget grid/firm-partners/workspace/budgets/{uuid}/grid

Returns the budget cell grid for a version, with optional actuals.

GET
List budget versions/firm-partners/workspace/budgets/{uuid}/versions

Returns version summaries for a budget.

POST
Create budget version/firm-partners/workspace/budgets/{uuid}/versions

Creates a new numbered version for the budget.

PATCH
Update budget cells/firm-partners/workspace/budgets/{uuid}/versions/{versionNumber}/cells

Updates one or more cells in a budget version.

POST
Bulk update budget cells/firm-partners/workspace/budgets/{uuid}/versions/{versionNumber}/cells/bulk

Applies many cell updates in one request with per-row success/failure results.

POST
Publish budget/firm-partners/workspace/budgets/{uuid}/publish

Publishes a budget version snapshot.

POST
Archive budget/firm-partners/workspace/budgets/{uuid}/archive

Archives a budget.

POST
Duplicate budget/firm-partners/workspace/budgets/{uuid}/duplicate

Creates a copy of a budget, optionally carrying cell values forward.