The Cheat Sheet I Wish I had before Building our Zapier Integration

Becca Saines
Jan 24, 2018 · 7 min read

Imagine explaining how to use Instagram to your 30-something’s co-worker. Now imagine explaining Instagram to your 80-something’s grandmother.

Documentation is mission critical to the success of a new developer product, but finding the sweet spot for maximizing audience engagement is no trivial task. Lucky for you, my loss (of time) is your gain. I hope this blog post will save you a ton of time, effort, and that you’ll be building on this reliably awesome tool faster than grandma can say “Snapchat”.


Another benefit of a dedicated glossary is being able to compare the keyword definitions for developers and non-technical end-users side by side. The Zapier documentation does do this to an extent (hats off, Zapier!) but still assumes a level of knowledge above what I had as a developer just beginning to work on Zapier.


  • Developer Definition — The current version of the code/scripting you’re working on. An app may be public, private, or invite only, but scripting for public/invite only apps can only be updated through a deploy of private apps. You are going to have a lot of private apps and that’s OK.


  • Developer Definition — The `POST` request (body comes from the Action Fields) made to the url I specify (Note: I am considering actions very separate from ‘Searches’ or other Zapier features that transform data mid-Zap).

Action Field

  • An Action Field is an input field for the user while they’re creating their Zap. It makes sense if you break down the words — it’s a field (that the user fills in) on the user-facing action part of a Zap. An Action Field represents the value of a key that becomes input to your scripting. Action Fields get passed as the body of the POST request made to your API endpoint when a Zap runs.

Parts of an Action

  • Noun: Not used in scripting. User-facing value for the object they’re working to create/update.
  • Key: Used in scripting! Used as a prefix to identify this action in code.
  • Help Text: Not used in scripting. Help text that the user will never read, because users rarely read anything, but Zapier still requires.


  • Developer Definition — Whether by polling or webhook, Zapier ends up with a JSON object to splice up. Values from specific keys of this object will be sent to the next step of the zap.

Trigger Fields

Parts of a Trigger

  • Bundle: The bundle is only ever referenced in the context of scripting — this is purely a developer-side keyword. The bundle is the object that is being updated; some of the data in the bundle might be sent as values to other API endpoints. The bundle contains headers for the request Zapier makes to any API endpoint you specify in your app, including any Auth information. Knowing where this Auth information lives is particularly useful if you’d like to make an additional request as part of your scripting logic.

Draw me a picture

Zapier Sushi

Printing and Logs


Step 1: Open the Scripting for your app.

Step 2: Under Quick links (top right corner), click on Bundle Logs

Step 3: The bundle logs are divided up by the functions that ran and a section for “The logs”. This is where you’ll find anything you’ve console.log()-ed.

Check out this sweet gif to see these steps in action!

Task History

For your first stop when debugging a Zap you’ve created (remember debugging a Zap is distinct from debugging your scripting), I suggest visiting the Task History. This will give you the `data in` and the `data out` for each step, even for steps belonging to different apps. The Task History will even give you some error messages.

Check this out if you prefer your information in video format.

Inspecting a Single Request

Step 1: From your app, find the category for the Request Log.

Step 2: Click on the original viewer.

Step 3: On the far right, click the buttons for More Details.

Step 4: Profit.

A note about the Original Viewer vs the New Log Viewer: You have two options for your log-viewing-pleasure in Zapier. The two viewers are very similar, but the new one has more options for you to filter on. At first I was partial to the Original Viewer but as time has gone on I’ve come to appreciate the diminished scrolling of the New Viewer. Examples of both the original and the new log viewers are below:

Original Viewer
New Log Viewer

Check out how to access the Original Viewer through the power of gif.

Super Important “Gotchas” that will save you oodles of time

  • You can return an empty array to stop a Zap (instead of throwing an error, which might potentially pause the Zap for the user if the error is thrown too many times).
  • Datetime: Zapier’s standard datetime format is an ISO-8601 formatted string. This means that if you receive a date from Zapier for a user’s action and your API expects a UNIX timestamp, you’ll need to use moment.js (thankfully a library Zapier Scripting allows access to) or `new Date()` to convert it via scripting before passing it to your API.
  • You can access information in the user’s Zapier profile via scripting! For instance, `bundle.zap.user.timezone`will give you the timezone the user entered on their Zapier profile.
  • Pre’s and Posts in Scripting: There are a lot of suffixes you can put on a key (that’s the thing from the trigger or the action that identifies which action/trigger you’re scripting about) — pre_poll, pre_read_resource, post_search, pre_write, etc. The myriad of options were really overwhelming for me when I first started developing features on our Zapier app. I wish someone has summed it up like this: pre_stuff is for before Zapier makes the request to your API. As a result, it’s mainly going to be used for things like adjusting the request url, or the headers of the request. The post_stuff is used after the request for data has been made, and so is mainly for adjusting the data you receive in the response to the request.

Streak’s integration with Zapier has enabled our users of varying technical capacity to really make the most out of our API. It’s been a fantastic tool to engage and create efficiency for our users through automation, and it’s all taken care of in a user-facing UI that’s friendlier than a border collie. A further plus is that Zapier’s support — both for developers and users — is top notch. I’ve been impressed with both the speed and quality of the support they consistently offer. As with any new technology tool, the learning tool can be steep. But the good news with Zapier is that you’re not going it alone.

Discuss on HN

Streak Engineering Blog

A blog documenting the technical journey of Streak

Becca Saines

Written by

Formerly a middle school math and science teacher, Becca joined Streak after graduating from Hackbright Academy. Her Patronus is a hummingbird.

Streak Engineering Blog

A blog documenting the technical journey of Streak