KPIs

The metrics this group defines, and each one's figure for a month with the target it is measured against.

The names

The endpoint

Method	Path	Answers
GET	`/api/v1/kpis`	Every KPI name the group can ask for

Needs a bearer token and the reference.read scope. It answers names only; a value is read for a company and a month under The values below.

What it answers

{
  "data": [
    { "name": "Cash Balance" },
    { "name": "Current Ratio" },
    { "name": "EBITDA" },
    { "name": "Gross Profit" },
    { "name": "Revenue" }
  ],
  "page": 1, "per_page": 50, "total": 56, "has_more": true
}

A custom KPI of the group's replaces a system metric of the same name, so a name appears once. It is the value a read states as metric, matched without regard to case.

The values

One metric, for one company and one month, with the target it is measured against and the variance between them.

The endpoint

Method	Path	Answers
GET	`/api/v1/organisations/{organisation}/kpi-values`	The metric's figure and its target

Needs a bearer token, a credential issued for that company, and the kpis.read scope. The names to ask for are at KPI names.

The parameters

Parameter	What it does
`metric`	The KPI name. Required.
`period`	The month, `Mon-YYYY`. Default: the reporting month.

What it answers

GET /api/v1/organisations/149/kpi-values?metric=Revenue&period=Sep-2026

{
  "metric": "Revenue", "period": "Sep-2026",
  "this_month": 63652.0, "this_month_ytd": 756527.0,
  "last_month": 97979.0,
  "change_from_last_month": 34327.0, "change_from_last_month_sign": "-",
  "change_from_last_year": 95906.0, "change_from_last_year_sign": "+",
  "target": 86316.0, "target_ytd": 792745.2, "target_method": 1, "auto_target": 0.2,
  "variance": 22664.0, "variance_sign": "-", "variance_direction": "down",
  "variance_ytd": 36218.2, "variance_ytd_sign": "-", "variance_ytd_direction": "down",
  "is_percentage": false, "progress": 73.74, "progress_ytd": 95.43, "spotlight": "Off Track"
}

Field	What it says
`this_month`, `this_month_ytd`	The value for the month and for the year to date. A month the ledger does not cover answers `0`, which is the figure the screen shows for it.
`last_month`	The previous month's value.
`change_from_last_month`, `change_from_last_year`	The size of the change from the previous month and from the same month a year earlier.
`change_from_last_month_sign`, `change_from_last_year_sign`	`+`, `-` or `=`: which way it moved, read the way the metric reads - `+` is the better direction.
`target`, `target_ytd`	The target the metric is measured against.
`target_method`, `auto_target`	How the target was set: the method the group saved against the metric and the percentage it applies, so a target can be understood without asking the settings screen.
`variance`, `variance_ytd`	The size of the difference between the figure and its target.
`variance_sign`, `variance_ytd_sign`	`+`, `-` or `=`: whether the figure is better (`+`) or worse (`-`) than the target. It is not arithmetic - a cost below its target reads `+`, because that is the good variance.
`variance_direction`, `variance_ytd_direction`	`up`, `down` or `eq`: the same reading as an arrow, for a screen that draws one.
`is_percentage`	Whether the metric is a percentage, so a figure is presented with the right unit.
`progress`, `progress_ytd`	The figure as a percentage of its target.
`spotlight`	`On Track` above 100% of target, `At Risk` from 80%, `Off Track` from 50%, `Critical` below - the label the screen shows.

A metric the group does not define answers 404, naming what was asked for.