How Your Brand is Used on Zapier#

We want Zapier users to have a consistent experience when interacting with the 1,000+ apps that are available on our platform. Because of this, we have some specific guidelines we require apps to follow.

Users will interact with your branding in a few different places within Zapier:

Zapbook#

The Zapbook is the full index of all the apps that are supported on Zapier. Users can discover apps by searching for them by name or filtering by category, popularity, etc.

Zapbook

Each app also has its own Zapbook page where we display the app logo, description, and some recommended Zaps that use the app. These recommended Zaps are templates that you'll set up before your app goes public.

Zap templates are pre-defined and curated examples of an automated workflow. It allows you to propose recommended use-cases, and provides users with a guided setup experience including pre-filled options and fields so they don't have to create them from scratch in the Zap editor. During the activation process, you'll learn more about creating Zap templates.

Explore#

The Explore section is another place a user may come in contact with your app. Here we allow users to select which apps they currently use or are interested in using and make recommendations on how Zapier can help integrate those apps.

Explore

In addition to Zap templates, we'll also show any relevant blog content to help users explore how they can use these apps with Zapier to automate their workflows. We feature partner apps in blog posts whenever it's fitting to the topic and useful for our audience.

Zap Editor#

The last place users will interact with your brand is within the Zap Editor itself. By the time a user is here, they likely know what app they want to use for their trigger or action, and will search for the app by name.

Editor

You can refer to the Branding section of the App Development Guide for more specific guidelines.

↑ Was this documentation useful? Yes No

How to Design A Successful Authentication Flow#

Connecting your app to Zapier should be smooth for users. To simplify connecting an account and minimize set up time for users, we recommend implementing OAuth.

If your API doesn't support OAuth, then the second best option is API keys, followed by a basic auth. Users should be able to obtain their auth information without requiring any additional human intervention. If your service requires users to e-mail/call your team in order to receive an API Key or access to your API, your integration won't be added to our public app catalog.

Basic auth, while acceptable, is the least appropriate authentication type to use for a third party service like Zapier, because the user has to type their username and password directly into our UI. Some users may be turned off by having to place their credentials into a service like Zapier. For that reason, OAuth and API Key based authentication are recommended.

You can refer to the Auth section of the App Development Guide for more specific guidelines.

↑ Was this documentation useful? Yes No

How To Design Successful Triggers#

The first launch of your app should have no more than three important triggers, and five total (visible) triggers. You can iterate over time with user feedback.

Focus on Popular Use Cases#

You'll want to design your triggers around how users interact with your app, and not based on your API endpoints. Triggers must be based on the most popular workflows your users would expect.

An example would be a “New Payment” trigger in an invoicing app. Most users would only care about successful payments, not pending ones. In this scenario, offer a “New Payment” trigger which only fires when the payment is marked success, regardless of whether the endpoint being requested has all types of payment statuses.

Another example might be a “New Email” trigger in an email app. Most users do not want to trigger on every new email received, rather a subset of all emails. Offer a trigger field to filter the emails that cause the Zap to fire.

Gmail

You can also focus on workflow scenarios, where some action inside your app triggers a Zap. For example, a “New Starred Email” trigger enables the user to do something in your app which then triggers a Zap.

Update Triggers#

Don't offer a generic "Item Updated" trigger. Instead, think under what scenario might the user need that. For example, Hubspot CRM offers a New Contact Property Changed trigger. The user can select a specific field to monitor, so only changes to that field will trigger the zap, giving the user significantly more control:

Hubspot

For Customer Relationship Management (CRM) apps that track opportunities or deals, users may care when a deal enters a certain stage. Instead of offering a Updated Deal trigger which triggers when anything changes, offer a New Deal in Stage trigger that allows the user to specify which stage they want to monitor.

Pipedrive

Choosing A Trigger Type#

Users want their automations to work quickly and efficiently. Depending on the user's Zapier plan, their Zaps will fire every 5 or 15 minutes if the triggers use polling methods. On the other hand, webhook Zaps will trigger instantly regardless of the user's plan. If your API supports it, implement REST hooks for your triggers.

While we do support static webhooks on our platform, we do not allow apps to go public with static webhook triggers as users can replicate that functionality on Zapier already via our built in Webhooks app, and supporting a static webhook is very difficult since the integration is controlled via user action that our support team can not inspect after the fact.

Trigger Fields#

Trigger fields allow users to filter the records that fire the Zap. Sometimes your API will require that a user select a trigger field, other times it will be optional. If a trigger field is required by your API and there is an obvious default value, then use that. For example, Dropbox's New File trigger defaults to the root directory.

Dropbox

Not all triggers need trigger fields. However, if a trigger returns records where the response data varies, allowing the user to select a trigger field makes setting up the Zap smoother. For example, a CRM app may have a New Contact trigger that returns both person and organization records. A person record may have fields like “First Name” or “Email” while an organization record may have fields like “Industry.” By adding a trigger field, you ensure that the response data is consistent from one record to the next.

Trigger fields are also important important for “New Activity” triggers that trigger off of events that happen within your app. These types of triggers tend to fire more frequently than users expect and giving users some control over what activities will trigger their Zap is recommended. For example, Trello's New Activity trigger allows you to choose specifically what sort of activity will trigger the Zap:

Trello

You can refer to the Trigger section of the App Development Guide for more specific guidelines.

↑ Was this documentation useful? Yes No

How To Design Successful Actions#

The first launch of your app should have no more than three important actions, and five total actions. You can iterate over time with user feedback.

Focus on Popular Use Cases#

As with triggers, you'll want to consider the user's workflow and not just build actions on top of your API endpoints. Basic actions create a single record in your app. For example, a CRM may have a Create Contact action where the user maps basic contact and demographic fields. The fields should in general follow a similar flow as when that record is created directly in the app itself.

Nutshell

Some fields require an ID or a specific string to be sent in order to properly create the item. In those cases, you'll want to provide a static or dynamic dropdown for the user to select from rather than expecting them to know the correct ID/exact text. For example, in Hubspot, the “Lifecycle Stage” is required to be one of the following choices:

Hubspot

Delete Actions Are Not Recommended#

Be cautious before adding an action that will delete records. Generally we strongly recommend avoiding these types of actions (especially for accounting and CRM apps), unless we hear from users that they really need this and it's a strong use case for your product. If you are considering adding a delete action for your app, we encourage you to consider alternative actions for records like deactivating, unsubscribing, or something similar instead of deleting records completely from your system.

Actions That Create Multiple Records#

There are some cases where a user will expect to be able to do something in a single action even though it requires multiple API calls.

For example, most e-commerce apps keep customer addresses in a separate table than customers. When creating a customer directly in the e-commerce app, a user would simultaneously create a customer address object. This behavior should be the same when creating a customer and customer address through Zapier, even though the result would be two API calls, one to the /customers endpoint, and one to the /customer_address endpoint. Because customer address objects are always related to customer objects, creating both in one Zapier action works well.

Shopify

On the other hand, there are some situations where allowing a single action to create multiple different objects becomes confusing for users. If the multiple objects you are trying to create are top-level, complex objects in your app, they should be separate actions within Zapier.

For example, with Salesforce, users can build a multi-step Zap that first creates an account with all the fields filled out, and then creates an opportunity that links back to the Account. The user can take advantage of the “Use A Custom Value” option and pass in the returned ID from the Create Account action.

Below, the screenshot on the left shows the Create Account action with all the fields filled out. The screenshot on the right shows the Create Opportunity action where the account is dynamically set by the results of the previous step.

Salesforce

Update Actions#

We recommend staying away from update actions unless you have a clear use case. There are several workflows where users may want to update records in an app. For example, changing the stage of a deal as it moves along with an Update Deal action make sense. Updating activities, notes, posts, and other items of this type isn't a common request and is confusing to implement.

The cleanest way to implement update actions is to keep them separate from the create actions. For example, Salesforce has three separate actions for contacts: Find, Create, or Update. This gives the user the most amount of control for how the data sent to the action app.

Salesforce

When To Throw Errors#

Your API should return a proper HTTP 4xx or 5xx error code when the action was unsuccessful. If your API returns HTTP 2xx, you'll need to add error interpretation into the scripting on your app to surface an error message to the user to let them know something went wrong.

Sometimes an action may result in a 4xx response, but it isn't considered an error from the user's perspective. In those cases, you'll also want to add scripting to Halt tasks instead of letting them error. For example, if a user tries to add a subscriber that is already on a Mailchimp list, Mailchimp will halt the action rather than throw an error.

Mailchimp

From a user's perspective, if the subscriber is already on the list, no additional action needs to be taken.

If, instead, Mailchimp let this result in an error, user's could have their Zaps turned off due to a high error 90% ratio, which is undesirable. When designing your actions, consider if your app has any similar scenarios.

You can refer to the Action section of the App Development Guide for more specific guidelines.

↑ Was this documentation useful? Yes No

How To Design Successful Searches#

The first launch of your app should have no more than three important searches, and five total searches. For many apps, searches aren't necessary for launch at all, and can be added later as advanced features. You can iterate over time with user feedback.

When You Should Consider Building Searches#

Searches in Zapier allow users to look up an item in your app. Depending on an app's actions, searches may be necessary to power other actions. For example, in order to create an invoice in Freshbooks, you need to select a client. Without a search, users would need to build a Zap for every client, which defeats the purpose of automation.

Freshbooks

Searches allow users to look up a client, then pass the results of the search step to the invoice step so that the invoices can be created per client dynamically with a single multi-step Zap.

Below, the screenshot on the left shows the Find Client action which looks up the client by email. The screenshot on the right shows the Create Invoice action where the client is dynamically set by the results of the previous step.

Freshbooks

How To Set Up Searches#

If you determine that your app does require searches, there are several ways to implement them. The best search use cases use a query field that will return a unique and expected result, or return nothing. For example, using an email to search for customers in a CRM would return the customer record if they exist or return nothing if they don't. Searches that return many results, like a search for a given document by keyword, may not be as usable, since users will have uncertainty about which item may be returned.

For most use cases, a single search field that is unique is sufficient, like Zoho CRM does for their Find Contact action.

Zoho

Lastly, if your search backend supports more advanced querying, you can build that into your search, but make sure to offer help documentation that spells out how the search works. Remember again that even with this method, we'll only return one record.

Airtable

Search or Create Options#

You can choose to make your searches a “Search or Create” by linking them to an existing Create action. For example, Freshbooks Find Client search allows you to create a client if one doesn't exist.

Freshbooks

This allows users to set up really clean and powerful workflows. Using this Freshbooks example, the user can search for an existing client, create one if it doesn't exist, and then create an invoice for that client all in one Zap.

You can refer to the Searches section of the App Development Guide for more specific guidelines.

↑ Was this documentation useful? Yes No
Get Help