Skip to content

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 ​

NameTypeDescription
targetPathstringRequired target containing the saved filter.
savedFilterIdstringRequired for update, remove, and delete. The saved filter's ID.
body.namestringRequired for create and update. The preset's display name.
body.typestringRequired for create and update. Must be form-submissions.
body.settingsobjectRequired for create and update. The complete preset settings.
body.settings.filterModestringRequired. Use basic or advanced; both use the same search conditions.
body.settings.searchobjectRequired. Search condition group containing match, conditions, and optional searchText.
body.settings.tableobjectRequired. Table settings described below.
body.settings.activeSitesstring[]Optional site IDs to include when resolving search references.
body.settings.templateIdstringOptional 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:

Operationdatamessage
CreateThe complete saved filter record.Saved filter created
UpdateThe complete updated saved filter record.Saved filter updated
RemovenullSaved filter removed
DeletenullSaved 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 removedAt and 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/restore with SUPER_ADMIN access. 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 under settings.search or settings.templateId.
  • 403: The caller lacks ADMIN access 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-filters
put/api/{targetPath}/saved-filters/:savedFilterId
post/api/{targetPath}/saved-filters/:savedFilterId/remove
delete/api/{targetPath}/saved-filters/:savedFilterId