Model MatchHelp

Saved Filters

Update a saved filter

patchapi.modelmatch.com/v1/saved-filters/{id}

Rename, re-icon, or replace the query / UI state (owner, editor, or workspace admin). The target is fixed. A new query is validated like on create. visibility / orgWidePermission change who can see it (owner or workspace admin only).

Authorization

x-api-keystringrequired

API key or OAuth token. See Authentication.

Path parameters

idstringrequired

Saved-filter id (nanoid).

Body application/json

fidelityenum

How much of the UI state query captures: exact; partial (see unmapped); ui_only — no runnable query. Defaults from whether query is present.

Options:exactpartialui_only
iconobject | null

Optional marker: one emoji. (Color dots and named icons were retired; existing ones were converted to the nearest emoji.)

Show child attributes
emojistringrequired
typeenumrequired
Options:emoji
namestring
orgWidePermissionenum

The whole workspace's role on an organization filter; null for private / shared filters.

Options:editorviewernull
queryobject | null

The target list operation's request body WITHOUT pagination (e.g. { flatFilters, filters, sort, period } for listOriginators). Validated against that operation's schema; unknown filter fields are rejected. Null/omitted for a UI-only filter.

Show child attributes
[key: string]null
uiStateobject | null

Opaque client UI state used to restore a filter panel (≤16KB). Not interpreted by the API.

Show child attributes
[key: string]null
uiStateVersioninteger
unmappedstring[]

UI filter keys the client could not express in query (set with fidelity: partial).

visibilityenum

Who can see the filter: private — only its owner; organization — every member of the workspace (view; edit too when orgWidePermission is editor); shared — only the members it was shared with (see /saved-filters/{id}/shares).

Options:privateorganizationshared

Responses

200objectThe updated filter.
Show attributes
dataobjectrequired
Show child attributes
canDeletebooleanrequired

You may delete it (owner or workspace admin).

canEditbooleanrequired

You may update its name, icon, query and UI state (owner, editor, or workspace admin).

canManageSharingbooleanrequired

You may change its visibility and who it is shared with (owner or workspace admin).

createdAtdatetimerequired
fidelityenumrequired

How much of the UI state query captures: exact; partial (see unmapped); ui_only — no runnable query. Defaults from whether query is present.

Options:exactpartialui_only
iconobject | nullrequired

Optional marker: one emoji. (Color dots and named icons were retired; existing ones were converted to the nearest emoji.)

Show child attributes
emojistringrequired
typeenumrequired
Options:emoji
idstringrequired
isOwnerbooleanrequired

True for your own filters; false for ones shared with you.

kindenumrequired

filter (default) — a saved search; view — a saved CRM table layout (columns / order) kept in uiState. Views never carry a query and have their own 25-per-target quota. Fixed at create.

Options:filterview
lastUsedAtdatetime | nullrequired

When it was last run; null if never.

namestringrequired
operationIdstring | nullrequired

The operation to run query against (e.g. listOriginators); null for UI-only targets.

ownerNamestring | nullrequired

The owner's display name on a filter shared with you; null on your own filters (and when it cannot be resolved).

ownerUserIdstringrequired

The user who owns it.

permissionenumrequired

Your role: owner, or the access it was shared with you at (editor / viewer; a filter visible to the whole workspace without an editor grant is viewer).

Options:ownereditorviewer
queryobject | nullrequired
Show child attributes
[key: string]null
queryVersionintegerrequired
stalebooleanrequired

True when the stored query no longer validates against the operation (its contract changed). Re-save or adjust before running.

staleIssuesobject[]required
Show child attributes
messagestringrequired
pathstringrequired
targetenumrequired

Which list the filter runs against. Market targets run against that entity's list operation (see operationId, e.g. listOriginators); crm_people / crm_companies are UI-only (filtered client-side).

Options:originatorsagentscompaniesbranchesofficesloanspropertiessalescrm_peoplecrm_companies
uiStateobject | nullrequired
Show child attributes
[key: string]null
uiStateVersionintegerrequired
unmappedstring[]required
updatedAtdatetimerequired
useCountintegerrequired

How many times the filter has been run: fetched with getSavedFilter, or named in X-MM-Saved-Filter-Id on a successful list request (count requests do not count).

visibilityenumrequired

Who can see the filter: private — only its owner; organization — every member of the workspace (view; edit too when orgWidePermission is editor); shared — only the members it was shared with (see /saved-filters/{id}/shares).

Options:privateorganizationshared
400objectValidation error — including a `query` that is not a valid request for the target's operation (`issues` lists each problem).
401objectUnauthorized
403objectNo active organization, or (`code: FORBIDDEN`) the filter is shared with you at a level that does not allow this.
404objectNo saved filter with that id is visible to the caller (their own, or shared with them).
413objectResponse payload too large — detail endpoint capped to fit Lambda response limits
503objectSearch timed out or the cluster is overloaded — retry after `Retry-After` seconds.