CRM v1 read-only
crm.
Counts and finds the workspace's CRM clients, optionally by part of the name, status, tag or creation date. Returns the total, the total per status and up to 15 clients with status, owner and creation day. No contact details and no notes.
Last updated
POST /api/v1/reads/crm.clients_search- Token scope
crm.clients_search@1- Workspace permission
api.crm.clients_searchoff 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 | |
|---|---|---|---|
search | string | optional | max 200 |
status | "lead" | "qualified" | "client" | "churned" | "reactivated" | "completed" | optional | |
tag | string | optional | max 100 |
createdSince | string (date-time) | optional |
Response — output when status is done
| field | type | rules | |
|---|---|---|---|
total | integer | required | ≥ 0 |
totalIsMinimum | boolean | required | |
byStatus | map<string, unknown> | required | |
clients | object[] | required |
clients[]
| field | type | rules | |
|---|---|---|---|
name | string | required | |
status | "lead" | "qualified" | "client" | "churned" | "reactivated" | "completed" | required | |
owner | string | null | required | |
createdOn | string | required | ^\d{4}-\d{2}-\d{2}$ |
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.clients_search \
-H "Authorization: Bearer $NIIKO_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
# 200 → done · 4xx → refused, with a named reasonWhy 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.searchClients() |
| niiko (Python) | niiko.search_clients() from 0.3.0 · not on the registry yet |
| niiko-cli | niiko read crm.clients_search |
| n8n-nodes-niiko | No reads: the node holds a key, and reading needs a person through OAuth. |
| niiko-mcp-server | crm_clients_search readOnlyHint |
History
- The SDKs and the CLI read
@vorluno/niiko-sdk,niikoandniiko-cli0.3.0 take an OAuth access token (accessToken,access_token=,niiko login --token) and have one read-only method per read:getCollections(),get_collections(),niiko read kiipu.collections_get. A read has two outcomes, done or refused, and takes no idempotency key. - Declared reads, OAuth only
POST /api/v1/reads/{id}answers nine declared reads — what is owed, what was collected, the agenda, the funnel, the month — never raw tables and never text someone wrote. Only with an OAuth token, on behalf of a person and with their role (an API key getsreads_need_a_person); each read has its own workspace switch, off by default. The MCP server lists them as read-only tools.