Available Methods#

There are a variety of methods for manipulating requests Zapier makes to your API. Below is the complete list of methods you can use in scripting. You may provide any, all, or none of these methods.

Trigger Methods#

Many of the trigger methods follow a naming pattern of key + method name, where key is the key given to the trigger when you created it. Below, we use the convention of TRIGGER_KEY as the placeholder for the trigger's actual key. For example, if you define a trigger with the key "my_trigger" and you want to implement the pre_poll method, you would write a method called my_trigger_pre_poll.

Polling#

  • TRIGGER_KEY_pre_poll - runs before the request to the polling URL, can modify the request before it is sent.
var Zap = {
  TRIGGER_KEY_pre_poll: function(bundle) {
    /* 
    Argument:
      bundle.request.url: <string>
      bundle.request.method: <string> # 'GET'
      bundle.request.auth: <array> # [username, password]
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.data: <string> # str or null

      bundle.url_raw: <string>
      bundle.auth_fields: <object>
      bundle.trigger_fields: <object> # the fields provided by the user during setup

      bundle.zap: <object> # info about the zap
      bundle.meta: <object> # extra runtime information you can use

    The response should be an object of:
      url: <string>
      method: <string> # 'GET', 'POST', 'PATCH', 'PUT', 'DELETE'
      auth: <array> # [username, password]
      headers: <object>
      params: <object> # this will be mapped into the query string
      data: <string> or null # request body: optional if POST, not needed if GET
    */
    return {
      url: bundle.request.url,
      method: bundle.request.method,
      auth: bundle.request.auth,
      headers: bundle.request.headers,
      params: bundle.request.params,
      data: bundle.request.data
    }; // or return bundle.request;
}
  • TRIGGER_KEY_post_poll - runs after we receive a response from the polling URL. Can parse the response to format the data that enters Zapier or throw an exception. We will throw for status codes 4xx and 5xx after the method runs automatically.
var Zap = {
  TRIGGER_KEY_post_poll: function(bundle) {
    /* 
    Argument:
      bundle.response.status_code: <integer>
      bundle.response.headers: <object>
      bundle.response.content: <str>

      bundle.request: <original object from TRIGGER_KEY_pre_poll bundle>

      bundle.auth_fields: <object>
      bundle.trigger_fields: <object> # the fields provided by the user during setup

      bundle.zap: <object> # info about the zap
      bundle.meta: <object> # extra runtime information you can use

    The response should be JSON serializable:
      [
        <object>, # with unique 'id' key
        <object> # with unique 'id' key
      ]
    */
    return [];
  }
}
  • TRIGGER_KEY_poll - runs in place of pre_poll and post_poll. You get a bundle and are expected to make the request and return a list of results or throw an exception. We will not throw for status codes like 4xx and 5xx automatically!
var Zap = {
  TRIGGER_KEY_poll: function(bundle) {
    /* 
    Arguments:
      bundle.request.url: <string>
      bundle.request.method: <string> # 'GET'
      bundle.request.auth: <array> # [username, password]
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the query string
      bundle.request.data: <string> # str or null

      bundle.url_raw: <string>
      bundle.auth_fields: <object>
      bundle.trigger_fields: <object> # the fields provided by the user during setup

      bundle.zap: <object> # info about the zap
      bundle.meta: <object> # extra runtime information you can use

      If you include a callback in the arguments, you can also perform async:
        callback(err, response)

    You are expected to make the request yourself. The response should be JSON serializable:
      [
        <object>, # with unique 'id' key
        <object> # with unique 'id' key
      ]
    */
    return []; // or callback(null, [])
  }
}

Static and REST Hooks#

  • TRIGGER_KEY_catch_hook - runs when we receive a static or subscription hook from your API. Can parse the response to format the data that enters Zapier.
var Zap = {
  TRIGGER_KEY_catch_hook: function(bundle) {
    /*
    Argument:
      bundle.request.method: <str> # 'GET', 'POST', 'PATCH', 'PUT', 'DELETE'
      bundle.request.headers: <object>
      bundle.request.querystring: <str>
      bundle.request.content: <str>

      bundle.cleaned_request: <object> or <array> # our best guess at parsing
                                                  # and combining the request
                                                  # (including handling JSON & XML).
      bundle.auth_fields: <object>
      bundle.trigger_fields: <object> # the fields provided by the user during setup

      bundle.zap: <object> # info about the zap

    The response should be either a JSON serializable array...
      [
        <object>,
        <object>
      ]

    ...or a single object:
      <object>
    */
    return []; // or {}
  }
}

REST Hooks and Notification REST Hooks#

  • pre_subscribe - runs before we subscribe.
var Zap = {
  pre_subscribe: function(bundle) {
    /*
    Argument:
      bundle.request.url: <string>
      bundle.request.method: <string> # 'POST'
      bundle.request.auth: <array> # [username, password]
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.data: <string> # str or null

      bundle.auth_fields: <object>
      bundle.trigger_fields: <object> # the data from trigger fields
      bundle.target_url: <string> # our unique Zapier url for this subscription
      bundle.event: <string> # the event being subscribed to

      bundle.zap: <object> # info about the zap

    The response should be an object of:
      url: <string>
      method: <string> # 'GET', 'POST', 'PATCH', 'PUT', 'DELETE'
      auth: <array> # [username, password]
      headers: <object>
      params: <object> # this will be mapped into the query string
      data: <string> or null # request body: optional if POST, not needed if GET
    */
    return {
      url: bundle.request.url,
      method: bundle.request.method,
      auth: bundle.request.auth,
      headers: bundle.request.headers,
      params: bundle.request.params,
      data: bundle.request.data
    }; // or return bundle.request;
  }
}
  • post_subscribe - runs after we subscribe. It is exclusively for storing results that are needed later for pre_unsubscribe.
var Zap = {
  post_subscribe: function(bundle) {
    /*
    Argument:
      bundle.response.status_code: <integer>
      bundle.response.headers: <object>
      bundle.response.content: <str>

      bundle.request: <original object from pre_subscribe bundle>

      bundle.target_url: <string> # our unique Zapier url for this subscription
      bundle.event: <string> # the event (if any) that was subscribed to

      bundle.auth_fields: <object>
      bundle.trigger_fields: <object> # the data from trigger fields

      bundle.zap: <object> # info about the zap

    The response should be JSON serializable, you'll have access to it as
    subscribe_data in the unsubscribe call. Normally you'd store some state
    about the hook resource you created, for example, some apps need
    an ID to locate and unsubscribe from a hook.

    */
    return ""; // or {}, or [] 
  }
}
  • pre_unsubscribe - runs before we unsubscribe.
var Zap = {
  pre_unsubscribe: function(bundle) {
    /*
    Argument:
      bundle.request.url: <string>
      bundle.request.method: <string> # 'POST'
      bundle.request.auth: <array> # [username, password]
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.data: <string> # str or null

      bundle.target_url: <string> # our unique Zapier url for this subscription
      bundle.subscribe_data <json> # any data you returned from post_subscribe
      bundle.event: <string> # the event (if any) being unsubscribed from

      bundle.auth_fields: <object>
      bundle.trigger_fields: <object> # the data from trigger fields

      bundle.zap: <object> # info about the zap

    The response should be an object of:
      url: <string>
      method: <string> # 'GET', 'POST', 'PATCH', 'PUT', 'DELETE'
      auth: <array> # [username, password]
      headers: <object>
      params: <object> # this will be mapped into the query string
      data: <string> or null # request body: optional if POST, not needed if GET
    */
    return {
      url: bundle.request.url,
      method: bundle.request.method,
      auth: bundle.request.auth,
      headers: bundle.request.headers,
      params: bundle.request.params,
      data: bundle.request.data
    }; // or return bundle.request;
  }
}

Notification REST Hooks#

  • TRIGGER_KEY_pre_hook - runs before the consuming call.
var Zap = {
  TRIGGER_KEY_pre_hook: function(bundle) {
    /*
    Argument:
      bundle.request.url: <string>
      bundle.request.method: <string> # 'GET'
      bundle.request.auth: <array> # [username, password]
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.data: <string> # str or null

      bundle.auth_fields: <object>
      bundle.trigger_fields: <object> # the fields provided by the user during setup

      bundle.zap: <object> # info about the zap

    The response should be an object of:
      url: <string>
      method: <string> # 'GET', 'POST', 'PATCH', 'PUT', 'DELETE'
      auth: <array> # [username, password]
      headers: <object>
      params: <object> # this will be mapped into the query string
      data: <string> or null # request body: optional if POST, not needed if GET
    */
    return {
      url: bundle.request.url,
      method: bundle.request.method,
      auth: bundle.request.auth,
      headers: bundle.request.headers,
      params: bundle.request.params,
      data: bundle.request.data
    }; // or return bundle.request;
  }
}
  • TRIGGER_KEY_post_hook - runs after we receive a response from the consuming call. Can parse the response to format the data that enters Zapier or throw an exception. We will throw for status codes 4xx and 5xx after the method runs automatically.
var Zap = {
  TRIGGER_KEY_post_hook: function(bundle) {
    /*
    Argument:
      bundle.response.status_code: <integer>
      bundle.response.headers: <object>
      bundle.response.content: <str>

      bundle.request: <original object from TRIGGER_KEY_pre_hook bundle>

      bundle.auth_fields: <object>
      bundle.trigger_fields: <object> # the fields provided by the user during setup

      bundle.zap: <object> # info about the zap

    The response should be JSON serializable:
      [
        <object>,
        <object>
      ]
    */
    return [];
  }
}

Available to all triggers#

  • TRIGGER_KEY_pre_custom_trigger_fields - runs before the request to the custom field URL (if provided).
var Zap = {
  TRIGGER_KEY_pre_custom_trigger_fields: function(bundle) {
    /*
    Argument:
      bundle.request.url: <string>
      bundle.request.method: <string> # 'POST'
      bundle.request.auth: <array> # [username, password]
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.data: <string> # str or null

      bundle.url_raw: <string>
      bundle.auth_fields: <object>
      bundle.trigger_fields: <object> # the fields provided by the user during setup

      bundle.zap: <object> # info about the zap

    The response should be an object of:
      url: <string>
      method: <string> # 'GET', 'POST', 'PATCH', 'PUT', 'DELETE'
      auth: <array> # [username, password]
      headers: <object>
      params: <object> # this will be mapped into the query string
      data: <string> or null # request body: optional if POST, not needed if GET
    */
    return {
      url: bundle.request.url,
      method: bundle.request.method,
      auth: bundle.request.auth,
      headers: bundle.request.headers,
      params: bundle.request.params,
      data: bundle.request.data
    }; // or return bundle.request;
  }
}
  • TRIGGER_KEY_post_custom_trigger_fields - runs after the response for custom fields is received. Can parse the response to format the data that enters Zapier or throw an exception. We will throw for status codes 4xx and 5xx after the method runs automatically.
var Zap = {
  TRIGGER_KEY_post_custom_trigger_fields: function(bundle) {
    /*
    Argument:
      bundle.response.status_code: <integer>
      bundle.response.headers: <object>
      bundle.response.content: <str>

      bundle.request: <original object from TRIGGER_KEY_pre_hook bundle>

      bundle.url_raw: <string>
      bundle.auth_fields: <object>

      bundle.zap: <object> # info about the zap

    The response should be JSON serializable:
      [
        # `type` can be unicode, int, bool
        # `key` should be unique and match a key found in the JSON representation we receive from your API
        # `label` is a human-readable name we can give this field in the UI
        {'type': <str>, 'key': <str>, 'label': <str>}
      ]
    */
    return [];
  }
}

Action Methods#

Action methods follow a naming pattern of key + method name, where key is the key given to the action when you created it. Below, we use the convention of ACTION_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.

  • ACTION_KEY_pre_write - runs before the request to the action URL, can modify the request before it is sent.
var Zap = {
  ACTION_KEY_pre_write: function(bundle) {
    /*
    Argument:
      bundle.request.url: <string>
      bundle.request.method: <string> # 'POST'
      bundle.request.auth: <array> # [username, password]
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.files: <object> # object of keys/arrays
                                     # * 1st item: filename str or null
                                     # * 2nd item: zapier.com endpoint that will stream the file
                                     # * 3rd item: mimetype str or null
      bundle.request.data: <string> # str or null

      bundle.url_raw: <string>
      bundle.auth_fields: <object>
      bundle.action_fields: <object> # pruned and replaced users' fields
      bundle.action_fields_full: <object> # all replaced users' fields
      bundle.action_fields_raw: <object> # before we replace users' variables

      bundle.zap: <object> # info about the zap

    The response should be an object of:
      url: <string>
      method: <string> # 'GET', 'POST', 'PATCH', 'PUT', 'DELETE'
      auth: <array> # [username, password]
      headers: <object>
      params: <object> # this will be mapped into the query string
      files: <object> # object of keys/arrays - experimental!
      data: <string> or null # request body: optional if POST, not needed if GET
    */
    return {
      url: bundle.request.url,
      method: bundle.request.method,
      auth: bundle.request.auth,
      headers: bundle.request.headers,
      params: bundle.request.params,
      data: bundle.request.data
    }; // or return bundle.request;
  }
}
  • ACTION_KEY_post_write - runs after we receive a response from the action endpoint, can modify the response or throw an exception. We will throw for status codes 4xx and 5xx after the method runs automatically. Note: If the action occurs as part of a search-or-create Zap, the output of this method is not exactly what the user sees. In that case, the action will be followed up with a request to fetch the written record, and we will present the user with the output from that follow-up request. If you need to modify the returned data in that scenario, use _post_read_resource.
var Zap = {
  ACTION_KEY_post_write: function(bundle) {
    /*
    Argument:
      bundle.response.status_code: <integer>
      bundle.response.headers: <object>
      bundle.response.content: <str>

      bundle.auth_fields: <object>
      bundle.action_fields: <object> # pruned and replaced users' fields
      bundle.action_fields_full: <object> # all replaced users' fields
      bundle.action_fields_raw: <object> # before we replace users' variables

      bundle.request: <original object from ACTION_KEY_pre_write bundle>

      bundle.zap: <object> # info about the zap

    The response will be used to give the user more fields to use 
    in the next step of the Zap.  Please return a JSON serializable object.

    return <object>;
    */
  }
}
  • ACTION_KEY_write - runs in place of pre_write and post_write. You get a bundle and are expected to make the request and return the appropriate response or throw an exception. We will not throw for status codes like 4xx and 5xx automatically! Note: If the action occurs as part of a search-or-create Zap, the output of this method is not exactly what the user sees. In that case, the action will be followed up with a request to fetch the written record, and we will present the user with the output from that follow-up request. If you need to modify the returned data in that scenario, use _post_read_resource.
var Zap = {
  ACTION_KEY_write: function(bundle, [callback]) {
    /*
    Arguments:

      bundle.request.url: <string>
      bundle.request.method: <string> # 'POST'
      bundle.request.auth: <array> # [username, password]
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.files: <object> # object of keys/arrays
                                     # * 1st item: filename str or null
                                     # * 2nd item: zapier.com endpoint that will stream the file
                                     # * 3rd item: mimetype str or null
      bundle.request.data: <string> # str or null

      bundle.url_raw: <string>
      bundle.auth_fields: <object>
      bundle.action_fields: <object> # pruned and replaced users' fields
      bundle.action_fields_full: <object> # all replaced users' fields
      bundle.action_fields_raw: <object> # before we replace users' variables

      bundle.zap: <object> # info about the zap

    If you include a callback in the arguments, you can also perform async:
      callback(err, response)

    The response will be used to give the user more fields to use 
    in the next step of the Zap.  Please return a JSON serializable object.

    return <object>;
    */
  }
}
  • ACTION_KEY_pre_custom_action_fields - runs before the request to the custom field URL (if provided).
var Zap = {
  ACTION_KEY_pre_custom_action_fields: function(bundle) {
    /*
    Argument:
      bundle.request.url: <string>
      bundle.request.method: <string> # 'POST'
      bundle.request.auth: <array> # [username, password]
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.data: <string> # str or null

      bundle.url_raw: <string>
      bundle.auth_fields: <object>
      bundle.action_fields: <object> # the raw action fields (if applicable)

      bundle.zap: <object> # info about the zap (details below)

    The response should be an object of:
      url: <string>
      method: <string> # 'GET', 'POST', 'PATCH', 'PUT', 'DELETE'
      auth: <array> # [username, password]
      headers: <object>
      params: <object> # this will be mapped into the query string
      data: <string> or null # request body: optional if POST, not needed if GET
    */
    return {
      url: bundle.request.url,
      method: bundle.request.method,
      auth: bundle.request.auth,
      headers: bundle.request.headers,
      params: bundle.request.params,
      data: bundle.request.data
    }; // or return bundle.request;
  }
}
  • ACTION_KEY_post_custom_action_fields - runs after the response for custom fields is received. Can parse the response to format the data that enters Zapier or throw an exception. We will throw for status codes 4xx and 5xx after the method runs automatically.
var Zap = {
  ACTION_KEY_post_custom_action_fields: function(bundle) {
    /*
    Argument:
      bundle.response.status_code: <integer>
      bundle.response.headers: <object>
      bundle.response.content: <str>

      bundle.request: <original object from ACTION_KEY_pre_custom_action_fields bundle>

      bundle.url_raw: <string>
      bundle.auth_fields: <object>

      bundle.zap: <object> # info about the zap

    The response should be JSON serializable:
      [
        # `type` can be unicode, int, bool
        # `key` should be unique, and will be the "key" in "key: value" in the POST
        # `help_text` and `label` are also available
        {'type': <str>, 'key': <str>}
      ]
    */
    return []; // return fields in the order you want them displayed in the UI. They'll be appended after the regular action fields
  }
}

Search Methods#

Search methods follow a naming pattern of key + method name, where key is the key given to the search when you created it. Below, we use the convention of SEARCH_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.

  • SEARCH_KEY_pre_search - runs before the request to the search URL, can modify the request before it is sent.
var Zap = {
  SEARCH_KEY_pre_search: function(bundle) {
    /*
    Argument:
      bundle.request.url: <string>
      bundle.request.method: <string> # 'POST'
      bundle.request.auth: <array> # [username, password]
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.data: <string> # str or null

      bundle.url_raw: <string>
      bundle.auth_fields: <object>
      bundle.search_fields: <object> # pruned and replaced users' fields

      bundle.zap: <object> # info about the zap

    The response should be an object of:
      url: <string>
      method: <string> # 'GET', 'POST', 'PATCH', 'PUT', 'DELETE'
      auth: <array> # [username, password]
      headers: <object>
      params: <object> # this will be mapped into the query string
      data: <string> or null # request body: optional if POST, not needed if GET
    */
    return {
      url: bundle.request.url,
      method: bundle.request.method,
      auth: bundle.request.auth,
      headers: bundle.request.headers,
      params: bundle.request.params,
      data: bundle.request.data
    }; // or return bundle.request;
  }
}
  • SEARCH_KEY_post_search - runs after we receive a response from the search endpoint, can modify the response or throw an exception. We will throw for status codes 4xx and 5xx after the method runs automatically. Note: The output of the method is not exactly what the user sees. We follow searches up with requests for the individual resources and present the user with the output from those follow-up requests. If you wish to modify the number (or ordering) of the search results, use _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.

var Zap = {
  SEARCH_KEY_post_search: function(bundle) {
    /*
    Argument:
      bundle.response.status_code: <integer>
      bundle.response.headers: <object>
      bundle.response.content: <str>

      bundle.auth_fields: <object>
      bundle.search_fields: <object> # pruned and replaced users' fields

      bundle.request: <original object from SEARCH_KEY_pre_search bundle>

      bundle.zap: <object> # info about the zap

    The response is an array, which may contain zero or more matches.

    If multiple matches are found, sort the array with the "best match" first.

    Use the available exceptions to vary errors.
    */
    return [ ]; // no matches
    /* --- or --- */
    return [ { ... } ];  // return a single match
    /* --- or --- */
    return [ { ... }, { ... }, ... ]; // several matches, with "best match" first
  }
}
  • SEARCH_KEY_search - runs in place of pre_search and post_search. You get a bundle and are expected to make the request and return the appropriate response or throw an exception. We will not throw for status codes like 4xx and 5xx automatically! Note: The output of the method is not exactly what the user sees. We follow searches up with requests for the individual resources and present the user with the output from those follow-up requests. If you wish to modify the number (or ordering) of the search results, you can do that inside _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.

var Zap = {
  SEARCH_KEY_search: function(bundle, [callback]) {
    /*
    Arguments:

      bundle.request.url: <string>
      bundle.request.method: <string> # 'POST'
      bundle.request.auth: <array> # [username, password]
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.data: <string> # str or null

      bundle.url_raw: <string>
      bundle.auth_fields: <object>
      bundle.search_fields: <object> # pruned and replaced users' fields

      bundle.zap: <object> # info about the zap

    If you include a callback in the arguments, you can also perform async:
      callback(err, response)

    The response will be used to give the user more fields to use 
    in the next step of the Zap.  Please return a JSON serializable object.
    */

    return {...}; // or callback(null, {...})
  }
}
  • SEARCH_KEY_pre_custom_search_fields - runs before the request to the custom field URL (if provided).
var Zap = {
  SEARCH_KEY_pre_custom_search_fields: function(bundle) {
    /*
    Argument:
      bundle.request.url: <string>
      bundle.request.method: <string> # 'POST'
      bundle.request.auth: <array> # [username, password]
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.data: <string> # str or null

      bundle.url_raw: <string>
      bundle.auth_fields: <object>
      bundle.search_fields: <object> # the raw search fields (if applicable)

      bundle.zap: <object> # info about the zap (details below)

    The response should be an object of:
      url: <string>
      method: <string> # 'GET', 'POST', 'PATCH', 'PUT', 'DELETE'
      auth: <array> # [username, password]
      headers: <object>
      params: <object> # this will be mapped into the query string
      data: <string> or null # request body: optional if POST, not needed if GET
    */
    return {
      url: bundle.request.url,
      method: bundle.request.method,
      auth: bundle.request.auth,
      headers: bundle.request.headers,
      params: bundle.request.params,
      data: bundle.request.data
    }; // or return bundle.request;
  }
}
  • SEARCH_KEY_post_custom_search_fields - runs after the response for custom fields is received. Can parse the response to format the data that enters Zapier or throw an exception. We will throw for status codes 4xx and 5xx after the method runs automatically.
var Zap = {
  SEARCH_KEY_post_custom_search_fields: function(bundle) {
    /*
    Argument:
      bundle.response.status_code: <integer>
      bundle.response.headers: <object>
      bundle.response.content: <str>

      bundle.request: <original object from SEARCH_KEY_pre_custom_search_fields bundle>

      bundle.url_raw: <string>
      bundle.auth_fields: <object>

      bundle.zap: <object> # info about the zap

    The response should be JSON serializable:
      [
        # `type` can be unicode, int, bool
        # `key` should be unique, and will be the "key" in "key: value" in the POST
        # `help_text` and `label` are also available
        {'type': <str>, 'key': <str>}
      ]
    */
    return []; // return fields in the order you want them displayed in the UI. They'll be appended after the regular search fields
  }
}
  • SEARCH_KEY_pre_read_resource - runs before we do the request to read an individual resource. Use to modify the request before it is sent.
var Zap = {
  SEARCH_KEY_pre_read_resource: function(bundle) {
    /*
    Argument:
      bundle.request.url: <string>
      bundle.request.method: <string> # 'GET'
      bundle.request.auth: <array> # [username, password]
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.data: <string> # str or null

      bundle.url_raw: <string>
      bundle.auth_fields: <object>
      bundle.read_fields: <object> # the response data from the search (or the write in case of search-or-create)
      bundle.read_context: <object> # the original params passed into the search (or the write in case of search-or-write)

      bundle.zap: <object> # info about the zap (details below)

    The response should be an object of:
      url: <string>
      method: <string> # 'GET', 'POST', 'PATCH', 'PUT', 'DELETE'
      auth: <array> # [username, password]
      headers: <object>
      params: <object> # this will be mapped into the query string
      data: <string> or null # request body: optional if POST, not needed if GET
    */
    return {
      url: bundle.request.url,
      method: bundle.request.method,
      auth: bundle.request.auth,
      headers: bundle.request.headers,
      params: bundle.request.params,
      data: bundle.request.data
    }; // or return bundle.request;
  }
}
  • SEARCH_KEY_post_read_resource - runs after we do the request to read an individual resource. Use to modify the data returned or throw an exception. We will throw for status codes 4xx and 5xx after the method runs automatically.
var Zap = {
  SEARCH_KEY_post_read_resource: function(bundle) {
    /*
    Argument:
      bundle.response.status_code: <integer>
      bundle.response.headers: <object>
      bundle.response.content: <str>

      bundle.request: <original object from SEARCH_KEY_pre_read_resource bundle>

      bundle.url_raw: <string>
      bundle.auth_fields: <object>
      bundle.read_fields: <object> # the response data from the search (or the write in case of search-or-create)
      bundle.read_context: <object> # the original params passed into the search (or the write in case of search-or-write)

      bundle.zap: <object> # info about the zap

    The response will be used to give the user more fields to use 
    in the next step of the Zap.  Please return a JSON serializable object.

    return <object>;
    */
    return {...};
  }
}
  • SEARCH_KEY_read_resource - runs in place of pre_read_resource and post_read_resource. You get a bundle and are expected to make the request and return the appropriate response or throw an exception. We will not throw for status codes like 4xx and 5xx automatically!
var Zap = {
  SEARCH_KEY_read_resource: function(bundle, [callback]) {
    /*
    Arguments:

      bundle.request.url: <string>
      bundle.request.method: <string> # 'POST'
      bundle.request.auth: <array> # [username, password]
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.data: <string> # str or null

      bundle.url_raw: <string>
      bundle.auth_fields: <object>
      bundle.read_fields: <object> # the response data from the search (or the write in case of search-or-create)
      bundle.read_context: <object> # the original params passed into the search (or the write in case of search-or-write)

      bundle.zap: <object> # info about the zap

    If you include a callback in the arguments, you can also perform async:
      callback(err, response)

      The response should be an object representing the resource. Can also use the available exceptions to vary errors.
    */
    return {...}; // or callback(null, {...})
  }
}

Authentication Methods#

  • pre_oauthv2_token - modify the request we'd send to the access token endpoint.
var Zap = {
  pre_oauthv2_token: function(bundle) {
    /*
    Argument:
      bundle.request.url: <string>
      bundle.request.method: <string> # 'GET'
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.data: <object>

      bundle.oauth_data: <object> # obj that contains your client_id, client_secret, etc...
      bundle.load: <object> # the params set to be sent as form/query string...

      bundle.zap: <object> # info about the zap

    The response should be an object of:
      url: <string>
      method: <string> # 'GET', 'POST', 'PATCH', 'PUT', 'DELETE'
      headers: <object>
      params: <object> # this will be mapped into the query string
      data: <string> or null # request body: optional if POST, not needed if GET
    */
    return {
      url: bundle.request.url,
      method: bundle.request.method,
      headers: bundle.request.headers,
      params: bundle.request.params,
      data: bundle.request.data
    }; // or return bundle.request;
  }
}
  • post_oauthv2_token - modify the response from the access token endpoint or throw an exception. We will throw for status codes 4xx and 5xx before the method runs automatically.
var Zap = {
  post_oauthv2_token: function(bundle) {
    /* 
    Argument:
      bundle.oauth_data: <object> # client id/secret and oauth related URLs
      bundle.response.status_code: <integer>
      bundle.response.headers: <object>
      bundle.response.content: <str>
      bundle.auth_fields: <object>
    */
    // If you have defined extra fields besides access_token 
    // and refresh_token in the Extra Requested Fields setup,
    // you may return them here as well.
    return z.JSON.parse(bundle.response.content);
  }
}
  • pre_oauthv2_refresh - modify the request we'd send to the refresh token endpoint. Only use if you have set the auth type for your App to be OAuth V2 with Refresh.
var Zap = {
  pre_oauthv2_refresh: function(bundle) {
    /*
    Argument:
      bundle.request.url: <string>
      bundle.request.method: <string> # 'GET'
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.data: <object>

      bundle.auth_fields: <object>
      bundle.oauth_data: <object> # obj that contains your client_id, client_secret, etc...
      bundle.load: <object> # the params set to be sent as form/query string...

      bundle.zap: <object> # info about the zap

    The response should be an object of:
      url: <string>
      method: <string> # 'GET', 'POST', 'PATCH', 'PUT', 'DELETE'
      headers: <object>
      params: <object> # this will be mapped into the query string
      data: <string> or null # request body: optional if POST, not needed if GET
    */
    return {
      url: bundle.request.url,
      method: bundle.request.method,
      headers: bundle.request.headers,
      params: bundle.request.params,
      data: bundle.request.data
    }; // or return bundle.request;
  }
}
  • Session Authentication: Zapier exposes a 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. That means, in your KEY_post_poll or KEY_post_write functions, you should raise an InvalidSessionException when your API denies a request due to missing or stale session credentials. Zapier will then call the following function and retry the request.

Zap = {
  get_session_info: function(bundle) {
    /*
    Argument:
      bundle.request.url: <string>
      bundle.request.headers: <object>
      bundle.request.params: <object> # this will be mapped into the querystring
      bundle.request.data: <object>

      bundle.auth_fields: <object>      
      bundle.zap: <object> # info about the zap
    */

   // Make z.request calls as needed. 

    // Returned object will be mixed into bundle.auth_fields in future calls.
    return {'api_key': api_key};
  }
};
↑ Was this documentation useful? Yes No
Get Help