Integrating a Form or Survey App on Zapier#

Overview#

  • For general concepts about how to create the best integration on Zapier, we recommend you read through the Planning Guide.
  • You should also read the App Development Guide, which provides a overview on best practices for how to implement your plan for your integration.

This guide discusses some unique key considerations (UX and technical) when building a form or survey integration with Zapier.

Trigger Names#

The most common trigger for a form app is a "New Form Entry/Submission" or "New Survey Response".

Using our standard "New xxx" naming pattern will help make it clear to users that Zapier will retrieve only new entries and not existing ones.

New Form Entry

Setup options for your Triggers#

Users will often have many forms or surveys set up in your app so you’ll need to add a field where they can choose which form or survey they want to receive results from.

The field type should be a dynamic dropdown which retrieves the form names exactly as they are listed in your app. Consider ordering the dropdown list by the most recently added to make it easier for users to find the form they are mostly likely to choose. This is the standard way to make it easy for users.

Dynamic Dropdown

In this example the form has been marked as required, but this isn’t necessary. If you make this field optional, the expected behavior is that it will trigger off responses to any form. We recommend adding help text to clarify what behavior will trigger it off when this field is optional and left blank.

Trigger response format#

Question and Answer Fields#

To make it easy for the user to map their answers into an action app, the fields need to be labelled appropriately. For example, in a form that asks for contact information, the question/field “What’s your email?” might be assigned a key that isn’t intuitive, like an id "1839dod38k01" or the generic label "Question 1." You’ll want to make sure each field’s key is given the human-readable label that the user has used in their form, so they’ll recognize which field to use when they’re mapping their action step. In the example below, each of the fields has been given labels (in bold) and is connected to an example value (in plain text).

Labeled question fields
  • A common use case is logging responses in spreadsheets with the answer fields being mapped to different columns. Using “q_1_answer” as a key name for a question is sensible, but for the label name you’ll want to specify the full question instead.
  • Consider returning the question number as a prefix to the label as well, to make it even easier for users to find particular questions.

Multiple choice fields#

If a multiple choice question is based on a spectrum of values (e.g., from "not really" to "very"), it’s sometimes useful to return the choice values as well as the actual answer. This can be especially useful for tracking in a spreadsheet.

Choice values and answer

Multi select fields#

If a user can select multiple responses (perhaps in a list of checkboxes), this can pose a challenge with how you want to return the data. Here’s an example of what that question might look like in the app:

Multiselects

Consider returning these by splitting each individual response to those questions into its own field. This is often easier to map into subsequent steps because the user can map them all into one field separated by the correct delimiter. Any checklist item not selected should return blank data. Here’s how the options would look while mapping:

Multiselect mapping

You can also return this in .CSV format. Users can then easily split the responses themselves with something like Formatter later on if they so wish. Here’s what this would look like, on another app:

CSV multiselect

Date Fields#

Date

As a minimum you’ll want to return the timestamp when the response was completed. This should be in ISO 8601 format.

File Attachments#

If a file attachments are supported on form entries you’ll want to make these available for use in subsequent action steps too. It is straightforward to implement the ability for Zapier to request the file with the necessary authentication at a later time (we call this file dehydration) using some basic scripting. You can also return the file object and the URL for it as separate fields.

Technical configuration#

REST Hooks#

We encourage you to implement REST Hooks because they offer a real time flow of data when form entries are completed. If you have a lot of form entries in a short space of time, webhooks can make your integration more robust as when using polling there is a chance the number of new entries will exceed your page size of polling results. The other benefit is we don’t need to repeatedly poll your API to check for new responses!

The format of the key/values in a hook should match the format for a polling URL item.

Polling URL#

The polling URL should return the most recent form entry for the chosen form, because it’s often more useful for a user to set up a Zap using a real entry they can recognize.

If there are no entries, you should return an empty list rather than a hard coded sample. We recommend this because every form/survey will be unique to each user, so there’s not a way to provide usable static sample data for this. With an empty list, the user is instructed to enter a new form entry when setting up a Zap or if they skip that option so they can still map fields loaded via the custom fields url.

Sample Result#

When defining a trigger or an action, a sample result should be provided. Sample results are used when there is a failure to retrieve data in the fetch step of setting up a Zap. Due to the nature of such a dynamic set of fields, it's hard to define a sample result for a form or a survey. The recommendation is to provide the bare set of common elements among all results. For example, if every result will have a timestamp, an example sample would be

{"id": 123, "timestamp": 1520250035}

Custom Fields URL#

Since your user’s forms are going to be unique we need to be able to load all the available fields for mapping. Whilst we can obtain these from polling, if it’s a brand new form then the polling result will return no entries so the custom fields URL is necessary to let all the fields be mapped.

Implementation checklist#

Once you’ve implemented your “New Form Entry” trigger, you should check to ensure your integration works well by creating Zaps for the following scenarios:

  • A form that already has completed entries
  • Check that your polling url is returning the latest form entry first (reverse chronological)
  • A brand new form that has no entries
  • A form that is composed of required and optional questions (you’ll want to make sure all the questions are mappable regardless of whether the latest response only had a few questions answered).
  • A form that has questions with multi select answers (e.g. choose one or more than apply to you to check that all the values come through)

Then go ahead and submit some new entries to check that the Zaps run as expected when they’re turned on.

Next Steps#

See our App Development Guide to learn more about other requirements for your integration such as branding. Read our activation checklist to learn about making your app available globally.

Feedback#

Please let us know if you found this guide useful or have any feedback on how we can improve it.

↑ Was this documentation useful? Yes No
Get Help