Save a reusable filter preset

When to use this endpoint

Use the Save preset action on a Jobs table, calendar or timeline. The server stores the UI filter payload; it does not execute that filter or verify its fields against the page.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. A tenant login is required.

Reads expose only filters owned by the current user or marked public=1. Writes require ownership or client-administrator permission; another user’s public filter is not editable merely because it is visible. Assigning or transferring ownership to another active tenant user requires client-administrator permission.

Parameters

Parameter	Type	Required	Description
`user_id`	Positive integer string	Yes	Active tenant owner. Must be the current user unless the caller has client-administrator permission.
`name`	String	Yes	Nonempty, maximum 182 Unicode characters. Not trimmed.
`filterdata`	Native JSON value or valid JSON string	Yes	Native structures are JSON-encoded once. Valid encoded JSON text is stored directly, not double-encoded. A scalar string value must be JSON-encoded explicitly.
`page_type`	String	Yes	Nonempty page key, maximum 80 characters; no supported-page enum.
`public`	Boolean or 0/1 or true/false string	No	Defaults private (0). Values outside the explicit boolean allowlist are rejected.
`id`	Nonnegative integer string	No	Omitted or 0 creates. Positive selects an existing authorized filter to update. Negative or malformed values are rejected.

Example request

$result = FM_api('UserFilter_save', [
	'user_id' => '1042',
	'name' => 'Northwind jobs',
	'page_type' => 'pageJobs',
	'public' => 'false',
	'filterdata' => ['searchValue' => 'Northwind', 'searchField' => ['All']],
]);

Example response

{"ok":1,"id":1088}

Errors and unusual responses

Response	Condition
`{"error":"not logged in"}`	No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
`{"error":"missing parameter: user_id"}`	Owner is absent; name/filterdata have corresponding missing-parameter messages.
`{"error":"missing or invalid parameter: pageType"}`	Page key absent, blank or over 80 characters.
`{"error":"filter owner does not exist"}`	Requested owner is missing or inactive.
`{"error":"missing or invalid parameter: id"}`	IDs must be positive integers; malformed/missing selectors are rejected.
`{"error":"filter with that ID does not exist"}`	Any selected target is absent.
`{"error":"filter permission denied"}`	A non-administrator targets another owner or attempts an unauthorized owner assignment.
`{"error":"configuration read failed"}`	A required database read fails; no write is committed.
`{"error":"configuration write failed"}`	Persistence or checked history fails; the transaction rolls back.
`{"error":"configuration transaction failed"}`	Transaction begin or commit fails; no success is reported.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

Create/update replaces owner, name, data, public and page_type. Creation sets cdate; updates preserve it. Use mapped updateData for a partial change.
No duplicate-name or filter-semantic validation. JSON syntax, lengths, flags, active owner and target authorization are checked. Unknown positive IDs cannot return success.

Side effects

Changed rows request their table’s cache marker. Row changes and history commit in one checked transaction; a write, history or commit failure rolls back the batch.
No customer/job data, notification or email is changed. No tenant feature setting alters this endpoint’s behavior.

See it in Fieldmotion

CRM1

On Jobs, Calendar or Timeline, configure filters and choose Save filter. The corresponding page script sends native filterdata, the current user, page key and public flag to UserFilter_save.

CRM2

Use Save preset on a CRM2 table. The shared filter UI in lib.js sends the current user and native filter object; editing a preset adds its ID and replaces the stored payload.

Related endpoints

UserFilters_get lists visible presets for the current user.
UserFilter_updateData can change selected mapped fields while preserving unspecified values.