MngGetClientsByFilter

Returns a paginated client table in the columnar structure + rows + count form.

The command is available through the manager command API only; there is no REST path for it. The kind is fixed by the command name, so customer_kind is not accepted on input. See Clients and Leads Commands.

It replaces the deprecated MngGetCustomersByFilter. There is no wrong-kind refusal here: the command simply returns clients and nothing else.

Access Control

Allowed sessions:

• SESSION_MANAGER
• SESSION_ADMIN
• SESSION_DEALER
• SESSION_CRM_MANAGER
• SESSION_CRM_ADMIN

The caller must have CRM access and see_clients. The requested deskFilter is intersected with the manager desk scope unless the manager has see_all_clients or admin scope, and brand must match the manager brand when brand scope is set.

contacts: "full" additionally requires see_clients_contacts; without it the request is refused with 403 rather than downgraded to masked values. A request that actually reveals contacts is written to the journal as a separate entry.

Request Parameters

Name	Type	Required	Description
deskFilter	string	Yes	Desk wildcard mask, for example *, DESK_*, DESK_EU*,!DESK_EU_TEST. Must not be empty
limit	int	Yes	Maximum rows, from 1 to 50000
offset	int	Yes	Pagination offset, 0 or greater
contacts	string	No	masked or full, default masked
where	array	No	[[field, operator, value], ...]
orWhere	array	No	OR comparison group; at least one condition must match
whereNot	array	No	[[field, value], ...]
whereIn	array	No	[[field, [values...]], ...]
whereNotIn	array	No	[[field, [values...]], ...]
whereBetween	array	No	[[field, [from, to]], ...]
whereNotBetween	array	No	[[field, [from, to]], ...]
orderBy	array	No	Example: [["created_time", "desc"]]

Filter fields and operators are the same as for the customer table, including the lifecycle_flags operators has_all, has_any, and has_none. Common filter semantics are described in Table filter syntax; desk masks in Desks TCP API.

Request

{
  "command": "MngGetClientsByFilter",
  "extID": "1",
  "data": {
    "deskFilter": "DESK_*",
    "limit": 50,
    "offset": 0,
    "where": [
      ["country_of_residence", "=", "CY"]
    ],
    "orderBy": [
      ["created_time", "desc"]
    ]
  }
}

Response Data

structure lists the column names and every row is a flat array of values in that same order. The columns are those of the customer table, described in Customer Fields. Read values positionally against structure rather than by a fixed index.

{
  "structure": ["customer_id", "full_name", "email", "phone", "desk", "lifecycle_flags", "customer_kind", "created_time"],
  "rows": [
    [1, "John Smith", "cl***@example.com", "+35***000", "DESK_EU", 5, 1, 1777700000]
  ],
  "count": 1
}

Field	Type	Description
structure	array	Ordered column names
rows	array	One nested array per record, values in structure order
count	int	Total number of matching records before pagination

count Matches the Page

The kind is selected before count is calculated and before the page is cut, so count describes clients only and a page never arrives short. A client does not have to filter the returned rows by kind afterwards.

Errors

HTTP	Error	Description
400	INVALID_DATA	Request validation failed
403	RET_NOT_ENOUGH_RIGHTS	Missing permission, missing scope, or the record is outside the caller's visibility
404	RET_NOT_FOUND	No customer with that identifier exists

Every error carries a message field with free-form text. Its contents are not part of the contract; branch on error.