CRM v1 read-only

`crm.month_summary_get`

Reads how the month is going, piece by piece and with the same figures each read would give: new clients, collected, proposals sent and accepted, deals won, appointments and the ledger result. A piece the person's role does not see, or whose read is off, comes back in unavailable.

Last updatedOct 18, 2026

POST /api/v1/reads/crm.month_summary_get

Token scope: crm.month_summary_get@1
Workspace permission: api.crm.month_summary_get off by default
Who reads: The person behind the token, with their role. Someone who leaves the workspace stops reading.

Three permissions

A token with that scope, the workspace owner having switched the read on, and the person's role seeing it in the product. None of them is enough alone. OAuth only →

Request

No fields.

Response — output when status is done

field	type		rules
`periodStart`	string	required	`^\d{4}-\d{2}-\d{2}$`
`periodEnd`	string	required	`^\d{4}-\d{2}-\d{2}$`
`newClients`	object \| null	required
`collected`	object \| null	required
`proposals`	object \| null	required
`dealsWon`	object \| null	required
`appointments`	object \| null	required
`monthResult`	object \| null	required
`unavailable`	object[]	required

newClients

field	type		rules
`total`	integer	required	≥ 0
`totalIsMinimum`	boolean	required
`byStatus`	map<string, integer>	required

collected

field	type		rules
`thisMonth`	string	required	`^-?\d+\.\d{2}$`
`samePeriodLastMonth`	string	required	`^-?\d+\.\d{2}$`
`outstanding`	string	required	`^-?\d+\.\d{2}$`
`openInvoices`	integer	required	≥ 0
`currency`	string	required

proposals

field	type		rules
`sent`	integer	required	≥ 0
`accepted`	integer	required	≥ 0
`acceptedUsd`	string	required	`^-?\d+\.\d{2}$`
`awaitingReply`	integer	required	≥ 0
`awaitingReplyUsd`	string	required	`^-?\d+\.\d{2}$`
`totalIsMinimum`	boolean	required

dealsWon

field	type		rules
`count`	integer	required	≥ 0
`totalUsd`	string	required	`^-?\d+\.\d{2}$`

appointments

field	type		rules
`count`	integer	required	≥ 0
`byStatus`	map<string, integer>	required
`totalIsMinimum`	boolean	required

monthResult

field	type
`currency`	string	required
`ledgerBalanced`	boolean	required
`month`	string \| null	required
`noActivityThisMonth`	boolean	required
`thisMonth`	object \| null	required
`previousMonth`	object \| null	required

thisMonth

field	type		rules
`revenue`	string	required	`^-?\d+\.\d{2}$`
`expenses`	string	required	`^-?\d+\.\d{2}$`
`netIncome`	string	required	`^-?\d+\.\d{2}$`
`closed`	boolean	required
`topRevenue`	object[]	required
`topExpenses`	object[]	required

topRevenue[]

field	type		rules
`account`	string	required
`amount`	string	required	`^-?\d+\.\d{2}$`

topExpenses[]

field	type		rules
`account`	string	required
`amount`	string	required	`^-?\d+\.\d{2}$`

previousMonth

field	type		rules
`month`	string	required	`^\d{4}-\d{2}$`
`revenue`	string	required	`^-?\d+\.\d{2}$`
`expenses`	string	required	`^-?\d+\.\d{2}$`
`netIncome`	string	required	`^-?\d+\.\d{2}$`

unavailable[]

field	type		rules
`piece`	"new_clients" \| "collected" \| "proposals" \| "deals_won" \| "appointments" \| "month_result"	required
`reason`	"role" \| "off"	required

Example

# Reads take an OAuth access token, not an API key, and no idempotency key: reading changes nothing.
curl -X POST https://niiko.org/api/v1/reads/crm.month_summary_get \
  -H "Authorization: Bearer $NIIKO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
# 200 → done · 4xx → refused, with a named reason

Why it may refuse

Each reason names who can fix it and how; detail.message, when present, says what to do. Refusals & HTTP codes →

invalid_inputrole_forbiddengrant_offreads_need_a_person

In the clients

@vorluno/niiko-sdk	`niiko.getMonthSummary()`
niiko (Python)	`niiko.get_month_summary()` from 0.3.0 · not on the registry yet
niiko-cli	`niiko read crm.month_summary_get`
n8n-nodes-niiko	No reads: the node holds a key, and reading needs a person through OAuth.
niiko-mcp-server	`crm_month_summary_get` readOnlyHint

Request

Response — output when status is done

Example

Why it may refuse

In the clients

History