Overview#

This style guide is a reference you'll need to follow in order to ensure your app meets the requirements to go Global (be available to everyone) on Zapier. We'll use it as a checklist during the activation process before your app can go Global. In addition to this document, we also recommend reading our Planning Guide before you start building.

If your app does not adhere to these guidelines, it may not be considered for global review. Alternatively, you may have to do a lot more work after activation if you don't carefully review this guide and reference it often.

Note: this is a living and breathing document, we'll add and remove items as the Zapier platform evolves.

↑ Was this documentation useful? Yes No

Branding#

To ensure that users have a consistent experience when interacting with apps on Zapier, please follow these guidelines. You can read about where your brand will appear in the Planning Guide.

Copy#

  • Use the actual unique name of your app, don’t add on adjectives or phrases. Use “Evernote” not “Evernote Note Taking”.
  • Write a short description (up to 140 characters) of what the app does. A good example is Trello: *“Trello is team collaboration tool that lets you organize anything and everything to keep your projects on task.*” No flowery or overstated language (e.x. “The best CRM...” is not a good description). Explain what makes your app different. Don't mention Zapier here, just focus solely on describing your service.
  • Use proper English and full sentences.

Logo#

  • Logo should be a square, transparent logomark at least 256x256px in size (please use a bigger version if you have one available) and should be a PNG file. Don’t use your name in the logomark because it is not legible at small sizes. If you have no logomark please create one. The logo should have a transparent background, or, if you use a solid background color, round the corners 3% of the width.
↑ Was this documentation useful? Yes No

Authentication#

Before you start building your authentication flow, we recommend reviewing the guidelines in our Planning Guide.

Authentication Configuration#

  • If you use API Keys, provide adequate help text so that the user can easily connect their account to Zapier. A direct URL (or as direct as possible) should be provided in the help text to get the person to their API key. Write the help text in Markdown so that the link is embedded into the description:

Auth

  • If you use subdomains, use our “subdomain” auth field type so the user doesn’t have to guess what formatting you expect for the domain or interpret from help text. If you need a full domain, use scripting to ensure the small details are correct (like https:// or a trailing slash on the URL) for the user.

Authentication Testing#

  • Your test trigger should ping a dedicated endpoint to determine if an auth is valid or not. Many apps have an endpoint that is something like /me.json. This is perfect. If not, pick the resource that is most likely to return 2xx when a valid auth is set up. The last thing we want is a 4xx when a valid auth exists because there isn’t a resource at the test trigger endpoint.
  • If the authentication fails, return a message that tells the user what is invalid. For example "401 and said nothing" is bad, whereas "Your API Key does not appear to be valid" is better. This can be fixed by updating the response code delivered by the API or via scripting in Zapier.
↑ Was this documentation useful? Yes No

Triggers#

The first launch of your app should have no more than three important triggers, and five total triggers. You can iterate over time with user feedback. Before you start building your triggers, we recommend reviewing the guidelines in our Planning Guide.

Copy#

  • Each trigger should have a descriptive title cased name, a descriptive key, a noun, and a concise description. Use our standard phrasing for trigger descriptions “Triggers when…” and no more than four to five additional words. Two to three words is best.
  • Don't be redundant with help text. Only include it if you have something different to say from the field label. Help text should command the user to take action. For example “This field is the directory field for new files” is not good help text. “Pick which directory to watch for new files.” is good help text. Redundant help text teaches users to not read any help text at all, so important information can be missed.
  • Copy/help text should match what the app UI says. For instance, Dropbox calls directories "folders". The app should say "folders" everywhere. Sometimes, the app's API might say something different than the app's UI. In those cases, match the UI - not the API.

Trigger Fields#

  • Users should never be expected to type in an ID. Instead, leverage our dynamic dropdown functionality to offer the user a pretty list to pick from.

Polling Triggers#

  • Results returned by polling endpoints should be in reverse chronological order by created date.
  • Don't make the number of results returned too small. Returning 100 items is sufficient for most apps, but there may be scenarios where its common for users to perform an action that would trigger more than 100+ records at once. Make sure your app paginates the trigger results appropriately for most workflows.
  • Make sure we are keying off the proper ID field. By default, we use the field called id if it exists. If not, we look for the shortest field key with id in the key name. Finally, we do a hash over every field key/value as a fallback which usually provides very unexpected results. Make sure to re-write your primary key field to id using scripting.
  • Make sure that {variables} defined in the data source URLs are guaranteed to exist (no optional trigger fields). If they are optional, use scripting to handle the NULL case.
  • Provide a sample result for cases where no result is returned during testing. Sample data should contain only one record, not the entire return from the service with multiple records . For example, {"key": "value"} instead of [{"key": "value"}, {"key": "value2"}, ... ]. Sample data returned should be consistent with the data returned by a real poll.
  • In the sample data, set certain fields as important if you want them go to the top of the list for users.

Webhook Triggers#

  • Static Webhook triggers are no longer allowed in an app for Global usage. Users can replicate that functionality on Zapier already via our built in Webhooks app. A better app would include authentication and use REST hooks to provide the user with a more streamlined experience.
  • REST Hook triggers should have a Polling URL defined. Make sure that {variables} defined in the polling URLs are guaranteed to exist (no optional trigger fields). If they are optional, use scripting to handle the NULL case. This allows the user to easily set up a Zap without having to navigate to your service to create a new data element each time - which is what happens if you have a REST Hook trigger without a corresponding polling URL. If that's not possible, there should be a fallback sample result for standard fields. Sample data should contain only one record, not the entire return from the service with multiple records . For example, {"key": "value"} instead of [{"key": "value"}, {"key": "value2"}, ... ].
  • Make sure that data returned between the polling fallback URL and/or sample data is consistent with the data returned by the REST hook when the zap is live. If the trigger has trigger fields, make sure those are respected in the testing step.
  • In the sample data, set certain fields as important if you want them go to the top of the list for users.

Response Content#

  • Many Action apps in Zapier require two names - first/last or given/surname. This conflicts with some naming schemes around the world, but without a separated name field, your app may not be compatible with these apps. You should always provide a separated name field, and if you have full name already, you can provide that as well.
  • Whenever possible, separate the parts of an address instead of giving the complete address in a single field. Users may need to pass each part individually to an app in a subsequent step.
  • Date-time values should be given in standard ISO 8601 format, and should always include a time zone offset (even if it's UTC). Avoid UNIX/Epoch timestamps. You can modify date-times with Moment.js, which is available globally in Scripting.
  • Examples of acceptable date-time values:
    • 2016-12-15T01:15:13Z (or -0000 instead of Z)
    • 2016-12-01T12:32:01-0800
    • 2016-12-01T12:32:01-08:00
    • 2016-12-13 (for date-only values)
  • If your app is date/time focused like a scheduling or calendar app, considering also providing a “friendly” time stamp in addition to an ISO timestamp. For example: “Wednesday, November 10, 2016 9:00AM PST.”
  • Always set boolean values as “true” or “false”—avoid 1 and 0.
  • For picklists/dropdowns, always return the value name in addition to the ID so they can be used in subsequent steps.
  • If you include any post_poll methods which parse JSON using JSON.parse(), ensure you wrap this code in try/catch and raise a nicer ErrorException message to the user. If your API ever doesn't return JSON for whatever reason (maybe your servers go down, or an unexpected 500 error which returns HTML instead of JSON) this try/catch ensures the user won't see a raw Javascript exception.
  • If there are additional fields that seem especially confusing or not useful to users, use scripting to strip these out.
↑ Was this documentation useful? Yes No

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. Before you start building your actions, we recommend reviewing the guidelines in our Planning Guide.

Copy#

  • Each action should have a descriptive title cased name, a descriptive key, a noun, and a concise description. Use our standard phrasing for action descriptions “Create a new…” and no more than four to five additional words. Two to three words is best.
  • Don't be redundant with help text. Only include it if you have something different to say from the field label. Help text should command the user to take action. For example “This field is the directory field for new files” is not good help text. “Pick which directory to watch for new files.” is good help text. Redundant help text teaches users to not read any help text at all, so important information can be missed.
  • Copy/help text should match what the app UI says. For instance, Dropbox calls directories "folders". The app should say "folders" everywhere. Sometimes, the app's API might say something different than the app's UI. In those cases, match the UI - not the API.

Action Fields#

  • Order action fields logically. If you are unsure, look at how the action fields are ordered inside your app and mimic that. Generally place more optional, less used-fields towards the bottom.
  • Make as few fields "required" as possible. Required action fields should generally be listed at the top of the editor. If something doesn't have to be required, don't make it! If the API specifies a non-important field as required, use scripting to hard-code a default value if one is not provided by the user.
  • Users should never be expected to type in an ID. Instead, leverage our dynamic dropdown functionality to offer the user a pretty list to pick from.
  • Make sure that the Action Endpoint URL and the Custom Action Fields URL do not use any optional variables. If they do, make sure this is accounted for in scripting.
  • If the data is a list, use our built in List data type, rather than asking for comma separated data in a text field. This allows users to use data that contains your separator (like a comma) and not cause an issue, and it results in a nicer UI within the Zap Editor.

Response Content#

  • Make sure to send back information about the record that was created, especially IDs and any other useful data about the record.
  • Return 4xx error codes when an action is unsuccessful. If your API returns 2xx errors, add scripting to account for this.
  • Sometimes, expected failures may return 4xx or other exceptions but shouldn’t be a real error (as real errors will pause zaps if they meet a certain threshold). You should raise HaltedException using scripting.
  • If you include any post_write methods which parse JSON using JSON.parse(), ensure you wrap this code in try/catch and raise a nicer ErrorException message to the user. If your API ever doesn't return JSON for whatever reason (maybe your servers go down, or an unexpected 500 error which returns HTML instead of JSON) this try/catch ensures the user won't see a raw Javascript exception.
  • Date-time values should be given in standard ISO 8601 format, and should always include a time zone offset (even if it's UTC). Avoid UNIX/Epoch timestamps. You can modify date-times with Moment.js, which is available globally in Scripting.
  • Examples of acceptable date-time values:
    • 2016-12-15T01:15:13Z (or -0000 instead of Z)
    • 2016-12-01T12:32:01-0800
    • 2016-12-01T12:32:01-08:00
    • 2016-12-13 (for date-only values)
  • If your app is date/time focused like a scheduling or calendar app, considering also providing a “friendly” time stamp in addition to an ISO timestamp. For example: “Wednesday, November 10, 2016 9:00AM PST.”
  • Always return boolean values as “true” or “false”—avoid 1 and 0.
  • For picklists/dropdowns, always return the value name in addition to the ID so they can be used in subsequent steps.
  • If there are additional fields that seem especially confusing or not useful to users, use scripting to strip these out.
↑ Was this documentation useful? Yes No

Searches#

The first launch of your app should have no more than three important searches, and five total searches. You can iterate over time with user feedback. Before you start building your searches, we recommend reviewing the guidelines in our Planning Guide.

Copy#

  • Each search should have a descriptive title cased name, a descriptive key, a noun, and a concise description. Use our standard phrasing for search descriptions “Find a …” and no more than four or five additional words. Two or three is best.
  • Don't be redundant with help text. Only include it if you have something different to say from the field label. Help text should command the user to take action. For example “This field is the directory field for new files” is not good help text. “Pick which directory to watch for new files.” is good help text. Redundant help text teaches users to not read any help text at all, so important information can be missed.
  • Copy/help text should match what the app UI says. For instance, Dropbox calls directories "folders". The app should say "folders" everywhere. Sometimes, the app's API might say something different than the app's UI. In those cases, match the UI - not the API.

Search Fields#

  • Users should never be expected to type in an ID. Instead, leverage our dynamic dropdown functionality to offer the user a pretty list to pick from.
  • Make sure that the Search Endpoint URL, Resource URL, and the Custom Search Fields URL do not use any optional variables. If they do, make sure this is accounted for in scripting.
  • By default, we assume that searches require two GET requests, one to a search endpoint and one to a resource endpoint. If your search endpoint returns all the data and doesn't require the second call, you can account for this via scripting.

Response Content#

  • Never raise an error for no results. For example, 404 is an incorrect response when performing a search. If your API returns a 404 for search misses - please use scripting to return an empty list [] instead (note a _post_search won't work, you'll have to replace _search completely).
  • Many action apps in Zapier require two names - first/last or given/surname. This conflicts with some naming schemes around the world, but without a separated name field, your app may not be usable with these apps. You should always provide a separated name field, and if you have full name already, you can provide that as well.
  • Date-time values should be given in standard ISO 8601 format, and should always include a time zone offset (even if it's UTC). Avoid UNIX/Epoch timestamps. You can modify date-times with Moment.js, which is available globally in Scripting.
  • Examples of acceptable date-time values:
    • 2016-12-15T01:15:13Z (or -0000 instead of Z)
    • 2016-12-01T12:32:01-0800
    • 2016-12-01T12:32:01-08:00
    • 2016-12-13 (for date-only values)
  • If your app is date/time focused like a scheduling or calendar app, considering also providing a “friendly” time stamp in addition to an ISO timestamp. For example: “Wednesday, November 10, 2016 9:00AM PST.”
  • Always return boolean values as “true” or “false”—avoid 1 and 0.
  • For picklists/dropdowns, always return the value name in addition to the ID so they can be used in subsequent steps.
  • If there are additional fields that seem especially confusing or not useful to users, use scripting to strip these out.
↑ Was this documentation useful? Yes No
Get Help