Delete pinned search by ID

Saved searches are how agents find their work in Kustomer. Each one stores a search query in data, in the same format as the search API: a queryContext that sets what it returns (customers, conversations, messages, custom objects and so on), and, or and not criteria, sort, and up to 20 fields to return. When an agent opens a saved search, Kustomer runs that query live, so the list is always current. Admins create and edit saved searches in the agent desktop or through these endpoints. Saved searches belong to the org rather than to one user, and deleting one removes it for everyone, along with its place in folders and any pins.

Who sees a search

defaultVisibility sets who sees the search, and teamVisibilities and userVisibilities (up to 10 entries each, as { id, visibility }) add specific teams or users on top of that default. Each visibility value says where the search appears:

Older integrations use private, accessTeams and accessUsers instead. Kustomer keeps both forms in sync, but don't send both forms in the same request, or it fails with 422. icon, badgeColor and showBadge control how the search looks in the sidebar; with showBadge, the sidebar shows a live count of matching results.

Folders, order and pins

The sidebar order is one list for the whole org, returned by the positions endpoint as positions: items with type search or folder, where a folder has children that are searches. Folders can't be nested, and a folder must be empty before you delete it. Create a search inside a folder by sending folderId.

Without filter=all, the positions endpoint returns only the searches the current user can see, and leaves out folders that would be empty for them.

Pinned searches are personal: each user can pin up to five searches for quick access, and pinning a sixth fails with 400. Pinning the same search twice fails with 409, and Kustomer removes a pin if the user loses access to the search.

Which endpoint to use

PUT /v1/customers/searches/positions only reorders: send the complete tree with every existing search and folder, or the request fails with 400. Send the rev you last read to avoid overwriting someone else's change; if the order changed since then, the request fails with 409 Conflict, so read it again and retry. Search names must be 3 to 256 characters, and the number of saved searches an org can have depends on its plan.