MngUpdateClientsDeskByFilter

Reassigns the CRM desk for every client matching the supplied filter.

The confirm flag decides whether anything is written. With confirm: false the command runs every check and returns the counters describing what would happen, without touching a record. With confirm: true the same run also persists the change. The response shape is identical in both modes.

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 MngUpdateCustomersDeskByFilter.

Access Control

Allowed sessions:

• SESSION_MANAGER
• SESSION_ADMIN
• SESSION_DEALER
• SESSION_CRM_MANAGER
• SESSION_CRM_ADMIN

The caller must have CRM access and set_clients. The requested deskFilter is first narrowed to the desks the caller may see, and then every selected record is checked individually against the caller's brand and desk scope. Records outside that scope are reported as failures and are never written.

Every call is written to the journal, successful ones included.

Request

{
  "command": "MngUpdateClientsDeskByFilter",
  "extID": "1",
  "data": {
    "desk": "DESK_RETENTION",
    "confirm": false,
    "filter": {
      "deskFilter": "*",
      "limit": 100,
      "offset": 0
    }
  }
}

Request Data

Top level:

Field	Type	Required	Description
desk	string	Yes	Target desk code, up to 64 characters. An empty string clears the desk assignment
confirm	bool	Yes	false reports what would change without writing. true applies the change
filter	object	Yes	Record selection

filter object:

Field	Type	Required	Description
deskFilter	string	Yes	Desk wildcard mask, for example *, DESK_*, DESK_EU*,!DESK_EU_TEST. Must not be empty
limit	int	Yes	From 1 to 50000. Validated, but it does not limit how much is processed
offset	int	Yes	Minimum 0. Validated, but it does not limit how much is processed
where	array	No	[[field, operator, value], ...], all conditions must match
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.

Desk Validation

The target desk is normalized to uppercase and validated per record against that record's brand. A desk belongs to exactly one brand, so the same target can be valid for part of a mixed-brand selection and invalid for the rest, which fails those records with INVALID_DESK. Records already on the target desk land in skipped and are left untouched.

Response Data

Counters only, with no per-record rows, so the payload is the same size for four records or forty thousand.

{
  "confirm": true,
  "desk": "DESK_RETENTION",
  "matched": 1240,
  "updated": 900,
  "skipped": 338,
  "failed": 2,
  "failures": [
    {"customer_id": 1101, "error": "INVALID_DESK", "message": "Desk does not exist, is disabled, archived, or belongs to another brand"}
  ]
}

Field	Type	Description
confirm	bool	Echo of the request flag
matched	int	Records selected by the filter, kind, brand scope, and desk mask
updated	int	Records actually written. Always 0 when confirm is false
skipped	int	Records that already held the requested value
failed	int	Records that did not pass the per-record checks
failures	array	One entry per failure with customer_id, error, and an optional message. Present only when non-empty

Reading the Counters

After an applied run the identity matched = updated + skipped + failed holds. On a dry run updated is 0 by definition, and the number of records that would be written is matched - skipped - failed.

Response Statuses

Status	Condition
200	Dry run. Always, since nothing was meant to change
200	Applied, at least one record written, no failures
207	Applied, at least one record written, some failed
409	Applied, nothing was written

Once every record already holds the requested value, running the same request again yields updated: 0 with skipped equal to matched and therefore 409. That is an idempotent no-op, not a fault: tell the two apart by the counters.

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.