# About the Back Office Search API

The Back Office Search API searches a site's dashboard in one call. It looks through the dashboard's tools and settings pages, apps from the App Market, Help Center articles, and the business data of the apps installed on the site, such as contacts, orders and products. Use it to give a custom dashboard the same search results as the dashboard's own search.

With the Back Office Search API, you can:

- Search a site's dashboard for a term and show the matches grouped into sections.
- Open what the user clicks: a dashboard page, a section of a page, a modal, or a URL.
- Keep the user's recent searches on the site, so you can offer them before they type.

## How results are organized

A search response holds up to 10 sections, in the order to show them. Each section is one category, such as Tools & Settings, Apps or Contacts, with a heading in the caller's language and up to 50 results, in the order to show them.

A category has no section when the caller can't see it, when it matched nothing, or when it failed. A missing section doesn't mean the category has no matches. A category that didn't answer in time comes back as a section with no results, after the others, when there's room left among the 10.

Each result has a title, up to 3 lines to show under it, an icon or an image, and a list of actions. When the user clicks a result, run its actions in order: open a page or a URL right away, and move on from a modal only when it closes successfully. A modal closed any other way ends the run.

## Before you begin

It's important to note the following points before starting to code:

- Every method works on a single site, and each category returns only what the caller may see.
- Search can be called by a site's logged-in user or by an app. The recent searches methods work per user, so only a logged-in user can call them.
- Recent searches are kept per user and per site, and expire 30 days after the user last added a term. They're best effort: an invalid term is rejected, but a valid one that can't be stored doesn't fail the call, and a list that can't be read comes back empty.
- This API is in beta, and its shape may still change.

## Use cases

- [Add dashboard search to a custom dashboard](fallback::https://dev.wix.com/docs/api-reference/business-management/dashboard/back-office-search/sample-flows#add-dashboard-search-to-a-custom-dashboard)
- [Offer the user's recent searches](fallback::https://dev.wix.com/docs/api-reference/business-management/dashboard/back-office-search/sample-flows#offer-the-users-recent-searches)

## Terminology

- **Section**: The results of one category, such as Contacts, with its heading in the caller's language.
- **Category**: A kind of thing the search looks through, such as tools and settings, apps, help articles, or an installed app's business data.
- **Action**: What a click on a result opens: a page, a section of a page, a modal, or a URL.
- **Recent searches**: The last 10 terms a user searched for on a site, newest first.

@sdk_package_setup

# Back Office Search API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

## Add dashboard search to a custom dashboard

A custom dashboard can offer the same search as the site's own dashboard, so users find tools, apps, help articles and business data without leaving your page.

To add dashboard search to a custom dashboard:

1. When the user stops typing a term of at least 2 characters, call [Search](fallback::https://dev.wix.com/docs/api-reference/business-management/dashboard/back-office-search/search) with the term in `searchTerm`.
1. Show each returned section in the order it comes back, with `displayName` as its heading and its `items` below it. When `pagingMetadata.hasNext` is `true`, show the count as more than `pagingMetadata.count`, for example `50+`.
1. For each section with an `allResultsPage`, show a link that opens it: `page` is a dashboard page and `url` opens in a new tab. Use `allResultsPage.label` as the link text, or the section's `displayName` when no label is returned.
1. When the user clicks a result, run its `actions` in order. Open a page or URL right away, and continue after a modal only when it closes successfully.
1. When the user settles on the term, call [Add Recent Search](fallback::https://dev.wix.com/docs/api-reference/business-management/dashboard/back-office-search/add-recent-search) with it, so it's offered the next time they search.

## Offer the user's recent searches

Showing the terms a user searched for before helps them repeat a search without typing it again.

To offer the user's recent searches:

1. When the user opens the search box, call [Get Recent Searches](fallback::https://dev.wix.com/docs/api-reference/business-management/dashboard/back-office-search/get-recent-searches) and show `searchTerms`, newest first.
1. When the user picks a term, call [Search](fallback::https://dev.wix.com/docs/api-reference/business-management/dashboard/back-office-search/search) with it.
1. When the user edits a term you added in the same session into a new one, call [Add Recent Search](fallback::https://dev.wix.com/docs/api-reference/business-management/dashboard/back-office-search/add-recent-search) with the new term in `searchTerm` and the earlier one in `replacedSearchTerm`, so the list doesn't keep both.
1. When the user chooses to clear their history, call [Clear Recent Searches](fallback::https://dev.wix.com/docs/api-reference/business-management/dashboard/back-office-search/clear-recent-searches).

Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

value

BoolValue

Int32Value

StringValue

Earlier term to remove, which the user edited into this one, such as `dom` before they typed on to `domain`.
Only pass a term you added in the same session.

replacedSearchTerm

Term the user searched for. Spaces at the start and end are trimmed before the term is checked and saved.

searchTerm

AddRecentSearchRequest

AddRecentSearchResponse

Dashboard page ID: a page component's GUID or a Wix page name.

pageId

Path to open within the page, relative to the page's own route.

path

AllResultsBackOfficePage

Where a section's "Search in" link goes: a dashboard page or a URL, with the search term already in it.

Name of the place the link searches, in the caller's language, such as `Help Center`. When not returned, use the
section's `displayName`.

label

AllResultsPage

target

Dashboard page ID, as in `pageOptions.pageId`.

Where the section is, relative to the page's own route, such as `?focus=favicon`.

relativeUrl

AnchorOptions

A back office search finds matches for a term across a site's dashboard: its tools and settings
pages, apps, help articles, and the business data of its installed apps. A search stores no data
of its own. The results come back in sections, one per category.

BackOfficeSearchEntity

ClearRecentSearchesRequest

ClearRecentSearchesResponse

GetRecentSearchesRequest

searchTerms

GetRecentSearchesResponse

Values to open the modal with, by the name the modal reads each one by, such as `appDefId`. Pass them to the
modal as is. Empty when the modal needs none.

inputs

Dashboard modal ID: a modal component's GUID or a Wix modal name, such as `mediaManager`.

modalId

ModalOptions

Where to go within the page, relative to the page's own route, such as a product ID. Empty opens the page itself.

PageOptions

Where a click takes the user: a dashboard page, a section of a page, a modal, or a URL.

Action type. Matches the options object that is returned.

type

SearchAction

options

Open a dashboard page at one of its sections.

SearchActionType

What a click opens. Deprecated: use `actions`, whose first action this is.

What a click runs, in order. Start each action when the one before it is done: a page or link right away, a modal
when it closes successfully. A modal closed any other way ends the run. Empty when the result opens nothing.

actions

Line under the title. Deprecated: use `descriptions`, whose first line this is.

description

Up to 3 lines to show under the title, in order, such as an order's customer, total and date.

descriptions

Name of a Wix Design System icon for this result, such as `Settings`. Ignored when `imageUrl` is returned.

iconKey

Image to show instead of an icon, such as a contact's avatar or an app's logo.

imageUrl

Result title, such as a product name or a contact's full name.

title

SearchItem

SearchRequest

Sections, in the order to show them. A category that matched nothing has no section.

sections

SearchResponse

Where to see every result of this category, for a "Search in" link. Not returned when the category has no such
page.

Section heading, in the caller's language.

displayName

Matches in this section, in the order to show them, up to 50. Empty only when the category didn't answer in time; such sections
come after the others.

items

Category key, such as `tools`. Stays the same across searches.

How many `items` the section holds, and whether the category found more, for example to show `50+`.

SearchSection

How many results a section holds. A section isn't paged, so there are no offsets or cursors.

count

Whether the category found more than the section holds. Set whenever the section has items.

hasNext

Total number of matches the category has.

Currently not returned.

total

SearchSectionPagingMetadata

UrlOptions

Searches the site's dashboard for a term and returns the matches grouped into sections.

Each section is one category, such as Tools & Settings, Apps or Contacts, and the sections come
in the order to show them, up to 10. A category has no section when the caller can't see it,
when it matched nothing, or when it failed: a missing section doesn't mean the category has no
matches. A category that didn't answer in time comes back as a section with no items, after the
others, when there's room left among the 10.

Each category returns only what the caller may see: a user's own permissions, or an app's.

To keep the terms the user searched for, call [Add Recent Search](https://dev.wix.com/docs/api-reference/business-management/dashboard/back-office-search/add-recent-search).

Searches the site's dashboard for `domain` and returns the matches grouped into sections.

Search a site's dashboard

Search

SCOPE.BACK_OFFICE.SEARCH

Retrieves the terms the calling user searched for on this site, newest first, up to 10.

Recent searches are kept per user and per site, and expire 30 days after the user last added a
term. An empty list means the user hasn't searched on
this site, cleared their recent searches, or they couldn't be read: a read failure isn't returned
as an error.

To add a term, call [Add Recent Search](https://dev.wix.com/docs/api-reference/business-management/dashboard/back-office-search/add-recent-search).
To remove all of them, call [Clear Recent Searches](https://dev.wix.com/docs/api-reference/business-management/dashboard/back-office-search/clear-recent-searches).

Retrieves the terms the calling user searched for on the site, newest first.

Retrieve the user's recent searches

GetRecentSearches

Adds a term to the top of the calling user's recent searches on this site.

An earlier copy of the same term, in any letter case, is removed, and only the newest 10 terms
are kept. Call this once the user settles on a term, not on every keystroke.

When the user edits a term you added earlier in the same session, pass the earlier one in
`replacedSearchTerm` so the list doesn't keep both. Don't pass a term that was already in the list
when the session started, or an older search the user made is removed.

An invalid term is rejected. Saving a valid one is best effort: if it can't be stored, the call
still succeeds, so a successful call doesn't confirm the term was kept. Two calls close together may keep only the
later term, so wait for one call to finish before sending the next.

To retrieve the list, call [Get Recent Searches](https://dev.wix.com/docs/api-reference/business-management/dashboard/back-office-search/get-recent-searches).

Adds `domain` to the top of the user's recent searches, replacing `dom`, which the user typed earlier in the same session.

Add a term to the user's recent searches

AddRecentSearch

Clears the calling user's recent searches on this site.

Unlike adding, a failure to clear is returned as an error, so a successful call means the list
was cleared. An add sent at the same time may put a term back.

To add a term again, call [Add Recent Search](https://dev.wix.com/docs/api-reference/business-management/dashboard/back-office-search/add-recent-search).

Clears the calling user's recent searches on the site.

Clear the user's recent searches

ClearRecentSearches

{
  "backOfficeSearchEntity": {
    "id": "7f3c2a91-4d6e-4b8a-9c15-e2d0b7a6f348"
  }
}


Back Office Search Entity Object