Searches#

Overview#

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#

Name#

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

Example:
Find a Contact or Find Ticket

Noun#

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.

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

Key#

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 _.

Example:
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.

Example:
Finds a contact by email address.

Important#

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.

Hide#

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 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:
http://api.example.com/v2/clients.json or http://{{account}}.example.com/api/v1/projects.json

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 https://example.com/api/v2/leads?email={{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:
http://api.example.com/v2/fields.json or http://{{account}}.example.com/api/v1/fields.json

Read more about custom field formating here.

Resource URL#

The URL we can use to fetch a single record. This will be used to perform a follow-up GET on results we get back from the Search Endpoint (and in the case of a Search-or-Create Zap, the create step as well).

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

You will want to provide this in case your Search (or Create) Endpoint doesn't return all useful information about a record that you might get by fetching it directly.

Example:
https://api.example.com/v2/leads/{{id}}.json or https://{{account}}.example.com/api/v1/leads/{{id}}.json

Assuming your search would return something like:

[
  {
    "id": 124
  }
]

And you had an account Authentication variable, for example.

↑ Was this documentation useful? Yes No
Get Help