This guide provides instructions on editing and maintaining existing scripting methods for legacy web builder integrations that have been converted to either the Platform UI or Platform CLI.
Note: This guide isn’t for new integrations built in Platform CLI or Platform UI. For new integrations, use the Platform UI or the Platform CLI to build an integration in code.If you are creating new functionality, check maintaining your converted integration for the best way forward. Much like Code Mode, Zapier’s Web Builder Scripting was the previous way to allow you to directly manipulate the requests and responses that are exchanged between your app’s API and Zapier. It continues to be supported using both the Platform UI and CLI.
Zap
defined in this Scripting.js file. By default, it is a blank JavaScript object. You add to it by specifying one or more of the available methods. Each method accepts a single variable called bundle
, which is a JSON serializable object. The content of the bundle varies depending on the method you are implementing. The output of your method must also be a serializable object.
Below is an example of implementing a method to be a pass-through:
KEY
as the placeholder for the trigger’s actual key. For example, if you define a trigger with the key “my_trigger” and want to implement the pre_poll method, you would write a method called my_trigger_pre_poll
.
KEY_pre_poll
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_poll
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_poll
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_catch_hook
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
pre_subscribe
Note: This code is only valid for Zapier’s legacy web builder, and is mostly incompatible with Platform CLI and Platform UI).
post_subscribe
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
pre_unsubscribe
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_pre_hook
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_hook
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_pre_custom_trigger_fields
Note: Although this method does not end with result_fields
like there are for actions and searches it does in fact define custom fields and labels for the result (sample) of the trigger and not for its Edit Template step in the Zap editor.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_custom_trigger_fields
Note: Although this method does not end with result_fields
like there are for actions and searches it does in fact define custom fields and labels for the result (sample) of the trigger and not for its Edit Template step in the Zap Editor.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY
as the placeholder for the action’s actual key. For example, if you define an action with the key “my_action” and you want to implement the pre_write method, you would write a method called my_action_pre_write
.
KEY_pre_write
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_write
_post_read_resource
.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_write
_post_read_resource
.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_pre_custom_action_fields
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_custom_action_fields
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_custom_action_fields
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_custom_action_result_fields
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_pre_custom_action_result_fields
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_custom_action_result_fields
KEY
as the placeholder for the search’s actual key. For example, if you define an search with the key “my_search” and you want to implement the pre_search method, you would write a method called my_search_pre_search
.
KEY_pre_search
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_search
_post_search
. If you wish to modify the data the user sees, use _post_read_resource
. One other thing to be aware of is that searches must return an array of objects, so if your search endpoint returns a single object, you can use this method to wrap your object in an array.
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.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_search
_search
. If you wish to modify the data the user sees, use _post_read_resource
.
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.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_pre_custom_search_fields
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_custom_search_fields
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_custom_search_fields
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_custom_search_result_fields
Note: This code is only valid for Zapier’s legacy web builder, and is mostly incompatible with Platform CLI and Platform UI).
KEY_pre_custom_search_result_fields
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_custom_result_search_fields
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_pre_read_resource
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_read_resource
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_read_resource
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
pre_oauthv2_token
Be aware that for legacy reasons the request does not follow RFC6749 and passes the parameters via the query string. If you define pre_oauthv2_token
then it is up to you correct this if needed. Without the method, Zapier will retry the request conform standards if the API returns an error on the first attempt.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
post_oauthv2_token
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
pre_oauthv2_refresh
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
get_session_info
get_session_info()
function for APIs that require any form of session-based authorization. Feel free to use the following skeleton function to inspire your session authorization:
Zapier will only invoke this function on an as-needed basis. It will be called when your API returns a 401 or when you raise anInvalidSessionException
in yourKEY_post_poll
orKEY_post_write
functions. Zapier will retry the request if the function returns new session info successfully.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
get_connection_label
get_connection_label()
function for APIs that need customization on their Connection Label:
Zapier will only invoke this function after the authentication is tested (when a new account is connected, and when the “test” button is pressed).
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
$
for jQuery (1.8.3), _
for Underscore (1.4.4), and moment
for Moment.js (2.0.0 with timezone), crypto
, and async
(0.2.9). Plus, it has some handy Zapier specific tools on the z
object!
Note: Do not use Underscore’s collection methods (_.each()
,_.map()
…) on objects. This will break if the object has alength
property. UseObject.keys(obj, fn)
instead.
root
, child_process
, Function
, module
, process
, global
, and setInterval
(they’ll be undefined
at runtime).
z.request
function allows you to make external calls. It performs in a synchronous manner for ease of use, but also provides standard asynchronous features as well if you pass an optional callback.
z.request(request, [callback])
var response = z.request()
request <Object>
: Takes all options for the NPM request package plus some that allow it to accept what most pre-scripting methods receive as bundle.request
:request <Object>
: Means you can also pass bundle
and we’ll extract bundle.request
to work with.auth <Array> | <Object>
: If auth
is an Array
, it will be transforrmed to {'user':auth[0], 'pass':auth[1]}
to match the package’s HTTP Authentication. If your Zapier app is configured to use Basic Auth then bundle.request.auth
will be array with 2 elements for the username and password. If it uses Digest Auth then the third element will be false
. In this case, when auth[2]
is set, Zapier will set auth.sendImmediately
to auth[2]
and also default jar
to true
since most digest servers require cookies.params <Object>
: Will become qs
unless that already exists.data <string>
Will become body
unless that already exists. While bundle.request.data
will always be a String
, be aware that body
also accepts a Buffer
, ReadStream
or - if json
is set to true
- any JSON-serializable object.callback Function ([error], response)
: Will be called on completion, with: - error <Error>
: Any error, when applicable. - response <Object>
: See Response.http.IncomingMessage
that matches what most post-scripting methods receive as bundle.response
:
status_code <number>
: The 3-digit HTTP response status code. E.G. 404
.headers <Array>
: Key-value pairs of header names (lower-cased) and values.content <string>
: If http.IncomingMessage.body
is a string
or Buffer
then we’ll wrap it in String()
.z.request()
without a callback and an error occurs, it will be thrown. Wrap your call in try/catch
block to handle it.
Please note that your scripts have 30 seconds, including waiting for and processing any requests. If you need to do lots of extra API calls, especially in a loop, you should look our hydration routine.
z.JSON.parse
function acts a lot like the native JSON.parse
, but adds some helpful logging and error handling.
z.JSON.parse(string)
, where string
is the string representation of a valid JSON object. An error will be thrown if the structure is invalid.
encoding
parameter) Zapier defaults to hex
and also support base64
as a parameter value. For input encoding (the input_encoding
parameter) Zapier default to binary
and also support utf8
as a parameter value. You should use utf8
if you expect data to be hashed that may include UTF8 characters.
The following hash algorithms are supported:
DSA-SHA1-old
, dsa
, dsa-sha
, dsa-sha1
, dsaEncryption
, dsaWithSHA
, dsaWithSHA1
, dss1
, ecdsa-with-SHA1
, md4
, md4WithRSAEncryption
, md5
, md5WithRSAEncryption
, mdc2
, mdc2WithRSA
, ripemd
, ripemd160
, ripemd160WithRSA
, rmd160
, rsa-md4
, rsa-md5
, rsa-mdc2
, rsa-ripemd160
, rsa-sha
, rsa-sha1
, rsa-sha1-2
, rsa-sha224
, rsa-sha256
, rsa-sha384
, rsa-sha512
, sha
, sha1
, sha224
, sha256
, sha384
, sha512
, ssl2-md5
, ssl3-md5
, ssl3-sha1
, whirlpool
get_contact
will not be called when post_poll is called. Instead, a unique hash is created and stored in place of deal.contact
.
There are two scenarios when get_contact
will then be called and “hydrated”.
deal.contact
may have keys to choose from on itself).
deal.contact
out to another app.
Please note that request will be done via the requests library for Python which is different from z.request(). You cannot set anauth
property (e.g. for Basic Auth). Instead provide the exactparams
andheaders
.
bundle.request
pre
and methods like KEY_write
receive a prepared request via bundle.request
. This object has the same format as what the pre
methods are expected. This means you can modify and return it. It is also the same format that z.request()
accepts. This is what you’d do in most KEY_TYPE
methods.
url <string>
: Configured Polling, Action or Search Endpoint URL. Any variables will be resolved.method <string>
: Will be GET
in most cases, but POST
for actions (_write
), pre_subscribe
and pre_unsubscribe
.auth <Array>
: Will only be set if the app’s Auth Type is Basic or Digest Auth. The first 2 elements are the username and password. Digest Auth has a third element which is always false
.headers <Object>
: If the Auth Type is API Key (Headers) or when it is OAuth V2, OAuth V2 (w/refresh) or Session Auth and you have selected Header or Both for Access Token Placement, then this object will have the required/mapped headers. In addition, Zapier always set Content-Type: application/json; charset=utf-8
and Accept: application/json
since data
defaults to JSON and Zapier prefer to get that back as well.params <Object>
: Will be mapped into the querystring. If the Auth Type is API Key (Query String) or when it is OAuth V2, OAuth V2 (w/refresh) or Session Auth and you have selected Querystring or Both for Access Token Placement, then this object will have the required/mapped parameters. If you need to convert this to an actual querystring, use $.param(bundle.request.params)
. Be aware that Zapier do not automatically set params for your Trigger Fields!data <string>
: Will form the body of the request. This will be set to a JSON string for pre_subscribe
, pre_unsubscribe
and actions (_write
) that have one or more fields with Send to Action Endpoint URL in JSON body enabled. To parse a JSON string back to an object use z.JSON.parse(bundle.request.data)
. To stringify an object use JSON.stringify(your_object)
.files <Object>
: For actions (_write
) that have file-type Action Fields this will be an object with the field keys as keys while the values are an Array
of: - [0] <string>
Filename or null
. - [1] <string>
URL to a zapier.com endpoint that will stream the file. - [2] <string>
Mimetype or null
.KEY_catch_hook
also receives bundle.request
, but as this is an incoming request it has a different structure. It does not have an url
or auth
property, params <Object>
is querstring <string>
and data
is called content
.
bundle.url_raw
bundle.url_raw
is simply the unrendered version of the URL with {% templatetag openvariable %}curlies{% templatetag closevariable %}
still intact.
bundle.auth_fields
bundle.auth_fields
is a javascript object that matches the authentication settings provided by the user when the API is connected. For example, if you have an authentication field of api_key
and subdomain
you can expect:
bundle.trigger_fields
or bundle.action_fields
bundle.trigger_fields
and bundle.action_fields
are javascript objects that surface the data given by a user to power a part of a zap. This is after rendering {% templatetag openvariable %}curlies{% templatetag closevariable %}
. These follow the trigger fields or action fields) you define. For example, maybe you have a field with a key list_id
and name
:
bundle.action_fields_full
if you want them included as well.
bundle.trigger_fields_raw
or bundle.action_fields_raw
bundle.trigger_fields_raw
or bundle.action_fields_raw
are javascript objects that surface the data given by a user to power a part of a zap. This is before rendering {% templatetag openvariable %}curlies{% templatetag closevariable %}
. These follow the trigger fields or action fields you define. For example, maybe you have a field with a key list_id
:
bundle.trigger_data
bundle.cleaned_request
bundle.cleaned_request
is our best guess at the parsed payload. Zapier does its best to parse JSON, XML and form-encoded data into respective javascript objects. If Zapier cannot parse it correctly - look into bundle.request.content
and parse it yourself.
bundle.zap
bundle.zap
object contains extra information about the zap (FYI: you may not see this information in debug bundles until the zap
is referenced at least once in your script):
bundle.meta
bundle.meta
object contains some runtime information about the Zap which you can use.
Use bundle.meta.page to implement pagination - this is especially important for triggers that power dropdowns.You can access the information for limited pagination features like this:
Note: This guide is for Zapier’s legacy web builder. If you use Platform UI, Zapier expects standard HTTP errors to be thrown. If you use Platform CLI, learn more in our CLI error handling docs.In scripting, you have several exception classes at your disposal:
ErrorException
. Use it in situations where the user has something misconfigured with their Zap and will need to take action. Typically, this will be for prettifying 4xx
responses and API’s that return errors as 200
with a payload that describes the error.
Example: throw new ErrorException('Your error message.');
If a Zap raises too many error messages it will be automatically turned off, so only use these if the scenario is truly an error that needs to be fixed.
HaltedException
. You might find yourself using this exception in cases where a required pre-condition is not met. For example, in an action to add notes to a contact where contacts are searched for by email address, you would want to throw a HaltedException
if a contact was not found. Unlike the ErrorException
, a Zap will never be turned off when this exception is raised (even if it is raised more often than not).
Example: throw new HaltedException('Your reason.');
Any pre_XXX call can be interrupted silently with StopRequestException
. This will prevent the request from being made and will never cause a user’s Zap to be turned off.
Example: throw new StopRequestException('Your reason.');
ExpiredAuthException
, the current call is interrupted, the Zap is turned off (to prevent more calls with expired credentials), and a predefined email is sent out informing the user to refresh the credentials.
Example: throw new ExpiredAuthException('Your message.');
For apps that use OAuth, but do not return a typical 401 when tokens expire, you can use the RefreshTokenException
in a post_XXX. This will signal to Zapier to attempt to refresh the access token and then repeat the failed call.
Example: throw new RefreshTokenException('Your message.');
InvalidSessionException
. This will tell Zapier to invoke your provided get_session_info()
function. Zapier will store these results for you and make them available to every poll
and write
. Zapier will throw the exception for you if the API responds with a 401 status.
Note This code is only valid for the v2 platform. It’s incompatible with Platform CLI and Platform UI.
Note This code is only valid for the v2 platform. It’s incompatible with Platform CLI and Platform UI.
Note This code is only valid for the v2 platform. It’s incompatible with Platform CLI and Platform UI.
Note This code is only valid for the v2 platform. It’s incompatible with Platform CLI and Platform UI.
Note This code is only valid for the v2 platform. It’s incompatible with Platform CLI and Platform UI.Sometimes, a search endpoint will return a successful response despite the search being unsuccessful. To account for this, you need to manipulate the response in a
_post_search
method:
Heads up! This code is only valid for the v2 platform, and is incompatible with today’s Platform CLI and Platform UI.
Note This code is only valid for the v2 platform. It’s incompatible with Platform CLI and Platform UI.
console.log
references, these will be translated to z.console.log
, so the console logs can be made available in our different logging tools.
For Platform UI: /build/test-auth#monitoring
For Platform CLI: /reference/cli-docs#logging