Appearance
Saved Filters
Create, replace, remove, and permanently delete shared form-submission search presets. Authentication and ADMIN access to the requested target are required. The only supported preset type is form-submissions.
All endpoints support site, organization, root tenant, organization tenant, and divisions under either tenant structure. Each target has its own presets; division endpoints do not read or write their parent tenant's presets.
Parameters
| Name | Type | Description |
|---|---|---|
targetPath | string | Required target containing the saved filter. |
savedFilterId | string | Required for update, remove, and delete. The saved filter's ID. |
body.name | string | Required for create and update. The preset's display name. |
body.type | string | Required for create and update. Must be form-submissions. |
body.settings | object | Required for create and update. The complete preset settings. |
body.settings.filterMode | string | Required. Use basic or advanced; both use the same search conditions. |
body.settings.search | object | Required. Search condition group containing match, conditions, and optional searchText. |
body.settings.table | object | Required. Table settings described below. |
body.settings.activeSites | string[] | Optional site IDs to include when resolving search references. |
body.settings.templateId | string | Optional form template ID. |
Create and update require the complete payload; update replaces settings rather than merging them. Remove and delete do not require a request body.
Table settings contain pageSize (number), sorting (array), columnOrder (string array), columnVisibility (boolean map), columnPinning (object with optional left and right string arrays), and columnSizing (number map). Sorting entries contain id (string) and desc (boolean), with optional path (string) and kind (number or date). Column map keys are logical column IDs and may contain dots. Row selection, drawer state, dashboard links, compiled requests, and client persistence metadata are outside the supported payload.
Conditions may declare reference metadata in metadata.refs. Each entry contains filterValue, schemaType, optional by: "name" (IDs are the default), and an optional ID prefix, such as "role:". References must match the selected scalar value or an entry in the selected array. References with schemaType: "field" identify field dependencies regardless of the comparison value. Name references resolve within the requested target and selected active sites. Field names alone do not declare references.
Required fields, container types, the preset type, the selected template, and declared references are validated. Search operators, condition keys, column schemas, and string formats are not fully validated. Missing or removed dependencies reject the write without changing the saved filter or its published reference. Active and inactive users can both be referenced.
Return Value
All four endpoints return HTTP 201 with data and message:
| Operation | data | message |
|---|---|---|
| Create | The complete saved filter record. | Saved filter created |
| Update | The complete updated saved filter record. | Saved filter updated |
| Remove | null | Saved filter removed |
| Delete | null | Saved filter deleted |
Create and update return a record with id, name, outer type: "savedSearch", and schema containing the submitted name, type: "form-submissions", and settings. IDs and timestamps are generated by the server. Updates preserve createdAt, refresh updatedAt, increment version, and replace settings. The returned internalRefs and internalRefIds are server-managed reference metadata; saving, restoring, and deleting a preset leave the referenced records unchanged.
Lifecycle
- Removal sets
removedAtand removes the preset from shared reads. Repeated removal succeeds without changing the timestamp. System presets and presets with active dependents cannot be removed. - Deletion permanently deletes an already removed, unused preset and cannot be undone.
- Restore a removed preset through
POST /api/{targetPath}/schema/:schemaId/restorewithSUPER_ADMINaccess. Restoration republishes the complete preset, including when its tracked references are missing or removed. Name conflicts and other schema restoration checks still apply.
Shared Reads
Users with read access to the target can read or subscribe to {targetPath}/references/saved-searches. This is an object keyed by saved filter ID, with each value containing the complete saved filter record. Create and update publish the current record; removal removes its entry. Direct client writes to this reference are denied.
Applying a saved filter does not grant access to matching submissions. Normal field validation and search authorization still apply.
Error Codes
400: Invalid input, missing or removed dependencies, an update to a removed preset, or a rejected remove/delete operation. Remove/delete also return this status for missing presets. Reference validation errors include paths undersettings.searchorsettings.templateId.403: The caller lacksADMINaccess to the requested target.404: The preset to update does not exist.409: The ID belongs to a different schema type; remove/delete also return this status for malformed schemas.
Examples
Create a preset. Use the same complete body with PUT /api/{targetPath}/saved-filters/:savedFilterId to replace it.
bash
curl -X POST "https://app.wombat.software/api/{targetPath}/saved-filters" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ..." \
-d '{
"name": "Open inspections",
"type": "form-submissions",
"settings": {
"filterMode": "basic",
"search": {
"match": "or",
"conditions": [
{
"__key": "group1",
"match": "and",
"conditions": [
{
"__key": "filter_type",
"field": "type",
"operator": "in",
"value": ["form"]
},
{
"__key": "filter_submittedOnly",
"field": "transitionHistory.state",
"operator": "exists"
}
]
}
],
"searchText": ""
},
"table": {
"pageSize": 25,
"sorting": [{ "id": "createdAt", "desc": true }],
"columnOrder": ["name", "createdAt"],
"columnVisibility": {},
"columnPinning": { "left": ["name"], "right": [] },
"columnSizing": {}
}
}
}'ENDPOINTS
post
/api/{targetPath}/saved-filtersput
/api/{targetPath}/saved-filters/:savedFilterIdpost
/api/{targetPath}/saved-filters/:savedFilterId/removedelete
/api/{targetPath}/saved-filters/:savedFilterId