CRM v1 read-only

`crm.client_overview_get`

Reads where ONE client named by name stands: their open invoices with balance and since when they are owed, the total owed, and which channels you have talked on with the day of their last message. Never what was said, and no phone or email.

Last updatedOct 22, 2026

POST /api/v1/reads/crm.client_overview_get

Token scope: crm.client_overview_get@1
Workspace permission: api.crm.client_overview_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

field	type		rules
`client`	string	required	min 1 · max 200

Response — output when status is done

field	type		rules
`client`	string	required
`owedTotal`	string	required	`^-?\d+\.\d{2}$`
`openInvoices`	object[]	required
`conversations`	object[]	required
`noActivity`	boolean	required

openInvoices[]

field	type		rules
`number`	string \| null	required
`balance`	string	required	`^-?\d+\.\d{2}$`
`currency`	string	required
`dueOn`	string \| null	required

conversations[]

field	type		rules
`channel`	string	required
`lastInboundOn`	string \| null	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.client_overview_get \
  -H "Authorization: Bearer $NIIKO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client": "…"
  }'
# 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_personambiguousnot_found

In the clients

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

History

Five more reads: the catalog, the knowledge base, a client's balance and overview, the agent's setupPOST /api/v1/reads/{id} answers five more declared reads: search the published catalog, search the knowledge base, how much one client owes, where one client stands (open invoices and the channels you talked on, never what was said) and how the sales agent is configured. Same rules as the first nine: OAuth only, the person's role, a workspace switch off by default. The MCP server lists them as read-only tools, and @vorluno/niiko-sdk, niiko and niiko-cli 0.4.0 add one method each.Oct 22, 2026