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
• Offer the user's 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.