KPIs

KPIs worked out from the books, outside data from other systems, and dashboards.

List KPIs

GET /kpis

Sends Vortex-Entity.

The KPIs the business can look at. Built-in ones have plain keys (revenue, cost_of_sales, gross_profit, operating_expenses, total_expenses, net_income, cash, receivable, payable, gross_margin, net_margin, revenue_growth, days_sales_outstanding, days_of_spending_owed, cash_runway). Custom KPIs, made in the app as one figure divided by another, have keys custom:<id>; outside data has keys metric:<id>. better is higher, lower or null. Custom KPIs and dashboards are made in the app; saving one with a name already used returns 409 duplicate_kpi or duplicate_dashboard, a tile naming a KPI the business doesn't have returns 422 invalid_kpi, a dashboard has up to 24 tiles (422 dashboard_full), and a dashboard whose stored tiles can't be read returns 422 dashboard_unreadable when changed. Requires reports:read.

Answers

  • 200 object. The KPIs and the periods they can be worked out for.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Work out KPIs for a period

GET /kpis/values

Sends Vortex-Entity.

Values of up to 24 KPIs, worked out from the books on accrual for period: this_month (so far), last_month (the default), year_to_date (from the start of the fiscal year) or last_12_months (the 12 full months before this one). Money moving in a period is what the period saw; balances (cash, receivable, payable) are as of its last day. Each value comes with the same period a year earlier (last_year), and trend=true adds the 12 months to the period's end. Values are decimal strings: currency to cents, percents as percent figures (42.5), days whole, months to one place. A KPI without a value says why in note; one that was removed has missing true. Requires reports:read.

Parameters

NameInTypeAbout
kpis requiredquerystring

KPI keys, separated by commas.

periodquerystring
trendquerystring
as_ofquerystring (date)

The day to work from; today by default.

Answers

  • 200 object. The values.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

List outside data

GET /metrics

Sends Vortex-Entity.

The business's outside data: numbers from other systems kept by month, such as headcount, appointments or ad spend. combine says how months add up to a longer period (sum, average or last). Outside data is defined in the app, or by a push to /metric-values. Requires reports:read.

Answers

  • 200 object. The numbers, each with its latest month and value.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Monthly values of one outside number

GET /metrics/{metric_id}/values

Sends Vortex-Entity.

From start_month to end_month (YYYY-MM; the last two years by default). Requires reports:read.

Parameters

NameInTypeAbout
metric_id requiredpathstring (uuid)
start_monthquerystring
end_monthquerystring

Answers

  • 200 object. The values, oldest first.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Send outside data

POST /metric-values

Sends Vortex-Entity.

Saves monthly values of outside numbers, named by key; a value of null clears that month. A number that doesn't exist yet can be described in metrics and is made first (one that exists is left as it is; a name already used by another key returns 409 duplicate_metric). A key the business doesn't have returns 422 unknown_metric and nothing is saved. Sending the same values again changes nothing: a month keeps its source and time until its value changes. In the app, values can also be typed or uploaded as a CSV or Excel file (a file that can't be read returns 422 unreadable_file). Requires events:write.

Body

FieldTypeAbout
metricslist of object
values requiredlist of object

Answers

  • 200 object. How many months were saved (new or changed) and cleared. A value sent again unchanged isn't counted.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

List dashboards

GET /dashboards

Sends Vortex-Entity.

The business's shared dashboards and, when a person is asking, their own personal ones. Each tile names a KPI, a period, an optional target and whether it shows a trend. Requires reports:read.

Answers

  • 200 object. The dashboards, shared ones first.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

A dashboard with its values

GET /dashboards/{dashboard_id}

Sends Vortex-Entity.

Every tile worked out now, as in /kpis/values, with on_target when the tile has a target. Requires reports:read.

Parameters

NameInTypeAbout
dashboard_id requiredpathstring (uuid)
as_ofquerystring (date)

Answers

  • 200 object. The dashboard.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Profit and loss insights for a month

GET /insights

Sends Vortex-Entity.

Findings about one month that is over (month, YYYY-MM; last month by default), worked out from the books and worded by fixed templates: net income and revenue against the month before and the same month a year earlier, gross margin moves, the accounts that changed most, spending well above its usual level, and new spending. A month that isn't over returns 422 month_not_over. Requires reports:read.

Parameters

NameInTypeAbout
monthquerystring
as_ofquerystring (date)

Answers

  • 200 object. The month's insights.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Alerts that stand today

GET /alerts

Sends Vortex-Entity.

Each alert says what was found, a recommended next step, and a link within the app. Rules: cash_low, overdue_invoices, bills_over_cash, revenue_drop, margin_drop, spending_jump, kpi_off_target, book_findings. Each is on by default with a default threshold; the business's owners, admins and accountants can turn one off or change its threshold in the app. settings lists each rule as it stands. Requires reports:read.

Parameters

NameInTypeAbout
as_ofquerystring (date)

Answers

  • 200 object. The alerts and the rules' settings.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what

Findings from the books checks

GET /book-checks

Sends Vortex-Entity.

Problems the ongoing checks of the books found, most serious first. check_key is one of duplicate_entry, duplicate_bill, unusual_amount, uncategorized, miscategorized, negative_balance, future_dated, off_day_entry, round_amount, stale_bank_lines. status filters by open (the default), dismissed, fixed or resolved. The checks run nightly and when someone runs them in the app, where people who keep the books dismiss or fix findings (in-app errors include finding_closed, finding_stale and fix_not_available). SYNC's AI can propose cleanup entries as proposals; approving one whose finding has changed since returns 409 proposal_stale. Requires ledger:read.

Parameters

NameInTypeAbout
statusquerystring

Answers

  • 200 object. The findings, and when the books were last checked.
  • 4XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what
  • 5XX Problem. An error. `code` is stable and safe to branch on; `detail` says in plain English what