KPIs
KPIs worked out from the books, outside data from other systems, and dashboards.
GET /kpisList KPIsGET /kpis/valuesWork out KPIs for a periodGET /metricsList outside dataGET /metrics/{metric_id}/valuesMonthly values of one outside numberPOST /metric-valuesSend outside dataGET /dashboardsList dashboardsGET /dashboards/{dashboard_id}A dashboard with its valuesGET /insightsProfit and loss insights for a monthGET /alertsAlerts that stand todayGET /book-checksFindings from the books checks
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
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
| Name | In | Type | About |
|---|---|---|---|
kpis required | query | string | KPI keys, separated by commas. |
period | query | string | |
trend | query | string | |
as_of | query | string (date) | The day to work from; today by default. |
Answers
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
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
| Name | In | Type | About |
|---|---|---|---|
metric_id required | path | string (uuid) | |
start_month | query | string | |
end_month | query | string |
Answers
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
| Field | Type | About |
|---|---|---|
metrics | list of object | |
values required | list 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
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
| Name | In | Type | About |
|---|---|---|---|
dashboard_id required | path | string (uuid) | |
as_of | query | string (date) |
Answers
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
| Name | In | Type | About |
|---|---|---|---|
month | query | string | |
as_of | query | string (date) |
Answers
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
| Name | In | Type | About |
|---|---|---|---|
as_of | query | string (date) |
Answers
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
| Name | In | Type | About |
|---|---|---|---|
status | query | string |

