Documentation

What is API Builder?

Today, Webhooks are a “fire-and-forget” mechanism, meaning you trigger them and only receive an acknowledgment that your request was received. To know if the Zap ran and get the output of that Zap, you have to look in Task History or the target systems of each step to see the output. While this works for background tasks, it is not ideal when you need to immediately surface the result of a Zap’s execution to your users.

Zaps as APIs allow you to turn your Zaps into an endpoint that is callable via HTTP requests and returns a response with the output of your Zap steps in one synchronous call.

Setup Instructions

  1. Log in to your Zapier account.

  2. Create a Zap.

  3. For your trigger app select API Builder by Zapier.

  4. Select the trigger New Request.

  5. In your trigger setup, no fields are required, but we do suggest that for the Request Parameters Types you enter key-value pairs of incoming parameters. Each parameter entered will then become available as sample data that can be mapped to following steps.

    • For example, if you want to accept an email and user_id as params, you would setup the field like so:
    • This means you will need to provide an email of type str and user_id of type int in your request body when calling the API.

  6. Click Continue to move to the testing section of the trigger.

  7. While in the Test section, click Test Trigger.

  8. Copy the api_url value. Save this URL for later (in this example we’ll use Postman to call the endpoint).

  9. Take note of the _callback field. You’ll use this later to tell the Zap when to return results via the endpoint.

  10. Create the middle steps of your Zap. In this example we’ll fetch a user by email from a table that serves as a database of users.

  11. Once you’ve created the rest of your Zap, you’ll need to make a POST request to the Callback URL provided in the trigger sample data.

  12. At the end of the Zap, add a Send Response action from the API Builder by Zapier app.

  13. Map the Callback field from the trigger to the Callback URL in your Send Response action.

    • Also, we recommend mapping data from previous steps in your response (as demonstrated below).
      • IMPORTANT: If you map a field to the data key-value pairs, and the step that the value refers to fails during execution, the Zap will timeout. This will return a timeout error when calling your Zap. To prevent this, use a Path to ensure a value exists, and if so, then callback.

  14. Publish your Zap.

Testing your API

  1. Open Postman.
  2. Paste the Gateway URL you copied earlier into your API Request.
  3. Include any required params in the request.
  4. Click Send to make the request.

Using an Access Token

API Builder allows you to set an Access Token in the "New Request" trigger. If there is an attempt to call the API URL without or with the incorrect Access Token, the API will return a 401 error.

The token can be included in either the API URL as a query param while making the call like this:

or it can be provided as a X-Token header like this:

Limitations

  • Dependent steps will result in cascading failures and if not handled, the API will return a (504) timeout response.

  • If a Zap results in multiple forks, the Send Response action that executes first will be the only data that is returned synchronously.

  • Loops are not supported before a Send Response step.

  • Autoreplays and retries due to rate limiting/app timeouts could cause the Zap to timeout in Gateway (max duration must be <=45 seconds).

Built on