Searches answer the question: What records can I lookup by a particular query? They are things like:

  • Find a Contact
  • Find a Product
  • Find an Issue

Searches can be useful on their own, or they can be combined with Actions to perform "Get or Create" style logic.

What a user sees:

What a developer sees:

See also: Searches in the CLI

You can define your searches via your app's dashboard. When you create a new search, you'll be prompted with several options. Below we list all complete definitions of what each option is for.

Search Options#


This is a human readable label a user would see when browsing the directory and adding your app. Make it short but descriptive.

Find Contact or Find Ticket


This is the object that the search is most closely associated with. It will be a noun you used in the Name field. We rely on an accurate noun to generate human-friendly sentences for users.

"Find Contact" would have "Contact" as the noun. "Find Completed Sale" would use "Sale" or "Completed Sale".


This is a field only really used internally for both dynamic dropdown and Scripting references. Needs to be at least two characters long, start with an alpha, and only contain a-z, A-Z, 0-9 or _.

find_contact, or findContact

Help Text#

A longer description of what this Search actually looks for. Point out any un-standard behavior as far as how searching happens.

Finds a contact by email address.


Usually you'll want to leave this checked, but if you don't we'll hide that search behind an "uncommon" link when a user selects their action. Mainly this is helpful for removing searches that are there for breadth but are rarely used.


Usually you'll want to leave this unchecked. If you check it, we'll completely hide the search from the enduser. This can be useful if a search is incomplete, but you need to deploy your app in it's current state. This option is also a way to hide searches that become deprecated in your API.

Search Endpoint#

Define the URL route where we will, by default, GET for a list of results. Note that the results must be an array, otherwise your search may fail. If there are no results, we expect an empty array. If your API returns a single object, you can use scripting to wrap the object in an array in a _post_search method. You can also make use of variable syntax where auth fields and search fields will be injected.

Example: or http://{{account}}

Note we'll only use the first object in the array for now, so if you can add optional fields to help narrow the search down, it's a great idea.

A Warning about encoding URL params#

We will not automatically encode any URL variables, so you're responsible for encoding any if they require that. For example, emails might include a + sign, so if you have{{email}} you'll want to encode that in your SEARCH_KEY_pre_search (or remove it from there and add it to the bundle.request.params), otherwise you'll get a "space" where the + sign is.

A better approach is to not even include it in the URL and to instead only use bundle.request.params in this case since bundle.request.params will be encoded automatically.

Custom Search Fields URL#

This allows you to dynamically define search fields that are user set (IE: custom fields).

Example: or http://{{account}}

Read more about custom field formating here.

Resource URL#

The URL we can use to fetch the full details of a Search result or (in the case of a Search or Action when no results are found) Create result. This is helpful because most searches only return a subset of a result's fields. It also ensures that regardless of it having found or created, the same data is returned.

If you leave this optional field blank, the raw Search or Create result will be used. You should only use this if the Search result has all relevant fields and you either configure no Search or Action or it returns the same fields as well.

You can make use of variable syntax where auth fields and search result fields (not the actual search fields) will be injected.

Assuming your search would return something like:

    "id": 124

And you configured this field with{{id}}.json then we'd GET to get the full result of the found or created item.

↑ Was this documentation useful? Yes No