Analytics

Close analytics: period flux and unusual entries.

GET /v1/entities/{entity}/analytics/breakdowns

Top customers, vendors, currencies and expenses

What a range is made of. customers: invoiced revenue per customer; vendors: billed spend per vendor; currency: invoiced revenue per document currency. All three are posted documents by document date, invoices less credit notes, at their net total in the functional currency (the document list filtered by the same party or currency, dates and posted status has the same documents). expense_mix: the expense accounts of the ledger by report line. The largest limit rows, the rest as one row other.

Parameters

Example request

curl "$ERP_URL/v1/entities/CH01/analytics/breakdowns?kind=value&start=2026-01-01&end=2026-09-30" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "entity": "string",
  "kind": "currency",
  "currency": "string",
  "start": "2026-09-21",
  "end": "2026-09-21",
  "total": "string",
  "rows": [
    {
      "key": "C-DE",
      "label": "string",
      "amount": "string",
      "share_pct": 1.5,
      "documents": 1
    }
  ]
}

GET /v1/entities/{entity}/analytics/flux

Flux analysis of a period

Flux analysis: each account's P&L movement or balance-sheet balance against the previous regular period. A row is flagged when the variance reaches the materiality and 10% of the comparison; flagged rows come first. Amounts are in the entity's functional currency. Profit-and-loss accounts compare the period's movement, balance-sheet accounts the balance at the period's end. Without an earlier period the comparison is empty. An unknown year or period answers 404.

Parameters

Example request

curl "$ERP_URL/v1/entities/CH01/analytics/flux?fiscal_year=2026&period=9" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "period": "string",
  "comparison": "string",
  "materiality": "string",
  "rows": [
    {
      "account": "string",
      "name": "string",
      "type": "string",
      "current": "string",
      "comparison": "string",
      "variance": "string",
      "variance_pct": 1.5,
      "flagged": true
    }
  ]
}

GET /v1/entities/{entity}/analytics/insights

What moved, in words

The accounts whose movement (profit and loss) or balance (balance sheet) differs from the comparison range by at least the materiality and 10%, largest first, each with one sentence made from its numbers by a fixed template; and the entries of the range that carry a risk flag. The same rules as /flux and /unusual-entries, for any range.

Parameters

Example request

curl "$ERP_URL/v1/entities/CH01/analytics/insights?start=2026-01-01&end=2026-09-30" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "entity": "string",
  "currency": "string",
  "start": "2026-09-21",
  "end": "2026-09-21",
  "comparison": {
    "mode": "previous",
    "start": "2026-09-21",
    "end": "2026-09-21"
  },
  "materiality": "string",
  "flagged_total": 1,
  "flux": [
    {
      "account": "string",
      "name": "string",
      "type": "string",
      "current": "string",
      "comparison": "string",
      "variance": "string",
      "variance_pct": 1.5,
      "change": "cleared",
      "summary": "string"
    }
  ],
  "unusual_total": 1,
  "unusual": [
    {
      "id": "string",
      "number": "string",
      "date": "2026-09-21",
      "description": "string",
      "source": "string",
      "amount": "string",
      "created_by": "string",
      "created_by_type": "string",
      "reverses": "string",
      "flags": [
        "string"
      ]
    }
  ]
}

GET /v1/entities/{entity}/analytics/kpis

Key figures with comparison

Ten figures for a range, each against the same figure for a comparison range, each with a small trend: revenue, gross margin %, operating expenses, net income, cash, receivables, payables, DSO, DPO and working capital. Computed on the server from the posted ledger by report line (the definitions are the metric list of GET .../analytics/series); a flow is the range's total, a stock the balance on its last day. delta is the difference, favourable says whether it is good news.

Parameters

Example request

curl "$ERP_URL/v1/entities/CH01/analytics/kpis?start=2026-01-01&end=2026-09-30" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "entity": "string",
  "currency": "string",
  "start": "2026-09-21",
  "end": "2026-09-21",
  "comparison": {
    "mode": "previous",
    "start": "2026-09-21",
    "end": "2026-09-21"
  },
  "granularity": "month",
  "periods": [
    {
      "key": "2026-09",
      "start": "2026-09-21",
      "end": "2026-09-21"
    }
  ],
  "kpis": [
    {
      "key": "cash",
      "unit": "amount",
      "value": "string",
      "comparison": "string",
      "delta": "string",
      "delta_pct": 1.5,
      "direction": "down",
      "favourable": true,
      "spark": [
        null
      ]
    }
  ]
}

GET /v1/entities/{entity}/analytics/series

A metric over time

One metric per calendar month, quarter or year over a range, from the posted ledger in the entity's functional currency. A flow (revenue, expenses, ...) is what moved in the period; a stock (cash, receivables, ...) and an aging are as of the period's end; a ratio is computed from the period's own figures. The first and last period are clamped to the range, so the sum of a flow over the periods is the report total for the range (revenue over a range is revenue of the profit-and-loss report for it), and a stock at the last period is the trial balance as of end. by splits a flow or stock into one line per report line or account; its totals are the sums. One aggregate query reads the range (an aging reads the open documents once). More than 60 periods answers 422: ask for a coarser granularity.

The metrics (metric):

• revenue (amount): Credit less debit of the accounts of type revenue: the P&L's total revenue.
• expenses (amount): Debit less credit of the accounts of type expense: the P&L's total expenses.
• net_income (amount): Revenue less expenses: the P&L's net income.
• cost_of_sales (amount): Debit less credit of the report line pl.cost_of_sales.
• operating_expenses (amount): Debit less credit of the report lines pl.opex.* and pl.depreciation.
• gross_margin_pct (percent): (Revenue on pl.revenue less cost of sales) / revenue on pl.revenue x 100; empty when there is no such revenue.
• cash (amount): Balance at the period's end of the report lines starting bs.assets.current.cash (the Cash figure of the Role Center).
• receivables (amount): Balance at the period's end of the report line bs.assets.current.receivables (the receivables control account in the ledger).
• payables (amount): Balance at the period's end of the report line bs.liabilities.current.payables (the payables control account in the ledger).
• unearned_revenue (amount): Balance at the period's end of the report line bs.liabilities.current.contract_liabilities: what customers paid or were billed for goods and services not yet delivered (contract liabilities, deferred revenue).
• working_capital (amount): Report lines bs.assets.current.* less bs.liabilities.current.* at the period's end.
• dso (days): Open receivables without VAT at the period's end (from the documents: the carrying amount of each open customer invoice and credit note times its net total over its total) / revenue of the period x days in the period.
• dpo (days): Open payables without VAT at the period's end (from the vendor bills, as the receivables for DSO) / purchases of the period x days in the period; purchases are cost of sales plus the operating expenses that are bought on account (pl.opex.* except pl.opex.personnel). Capital purchases on account are not in purchases.
• receivables_aging (amount): Open customer invoices less credit notes as of the period's end, in the functional currency at the booking rate, in the buckets of the aging report (current, 1-30, 31-60, 61-90, 90+ days past due). Equals totals_functional of GET /v1/entities/{entity}/reports/aging as of that day.
• payables_aging (amount): Open vendor bills less credit notes as of the period's end, as the receivables aging.

Parameters

Example request

curl "$ERP_URL/v1/entities/CH01/analytics/series?metric=value&start=2026-01-01&end=2026-09-30" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "entity": "string",
  "metric": "cash",
  "unit": "amount",
  "currency": "string",
  "granularity": "month",
  "start": "2026-09-21",
  "end": "2026-09-21",
  "by": "account",
  "periods": [
    {
      "key": "2026-09",
      "start": "2026-09-21",
      "end": "2026-09-21"
    }
  ],
  "lines": [
    {
      "key": "pl.opex.other",
      "label": "string",
      "values": [
        null
      ]
    }
  ],
  "totals": [
    "string"
  ]
}

GET /v1/entities/{entity}/analytics/unusual-entries

Unusual entries of a period

Posted entries of the period with risk flags: manual, created by an agent, round or large amount (10x materiality), weekend date, reversal. Each entry lists its flags and its total debits in the entity's functional currency. An unknown year or period answers 404.

Parameters

Example request

curl "$ERP_URL/v1/entities/CH01/analytics/unusual-entries?fiscal_year=2026&period=9" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

[
  {
    "id": "string",
    "number": "string",
    "date": "2026-09-21",
    "description": "string",
    "source": "string",
    "amount": "string",
    "created_by": "string",
    "created_by_type": "string",
    "reverses": "string",
    "flags": [
      "string"
    ]
  }
]

Schemas

Breakdown

BreakdownRow

ComparisonRange

Flux

FluxInsight

FluxRow

Insights

Kpi

Kpis

Series

SeriesLine

SeriesPeriod

UnusualEntry