Build a Zapier Integration to Connect Your API to 1,000s of Apps

Last Updated on November 25, 2022

Are you tired of coding up yet another time-consuming API integration? To seamlessly connect your API to any of 1,000s of services, Zapier could be the answer.

Once you’ve built a single integration for your custom API, Zapier offers the tooling to automate almost any process, using any number of services. All without writing any more code.

In this article, you’ll discover the main steps to create a Zapier integration. By following the build of a real-world integration, you’ll better understand how you might use Zapier in your situation.

How does Zapier help developers?

Zapier lets you connect any of 5,000 supported applications together, all through a straightforward UI.

It removes many of the frustrations developers experience when writing custom API integrations, by:

• seamlessly handling API calls
• authenticating requests
• handling errors
• hosting everything

Zapier is all about easily automating processes that are better done by a machine.

That could be creating Trello cards from new GitHub pull requests.

Or perhaps sharing content across social media.

In Zapier, an app represents a service that a user might want to use in an automation. Think GitHub, Gmail, or Slack.

Thanks to its thousands of apps, Zapier already covers many existing use-cases.

Behind an app is an API integration that developers have coded up and published onto the Zapier platform.

As a developer, you too can create a Zapier integration. Whether that’s to bring the power of your API to the world, or just to automate a time-consuming process using your favourite API, the possibliitlies are endless.

In the rest of the article, we’ll cover the main steps to create such a custom integration.

But first, it’s useful to know how to automate processes in Zapier using existing integrations, by creating what’s known as zaps.

Automate everything with zaps

A zap is an pipeline which automates one specific process. For example, creating Jira issues from new messages posted to a Slack channel.

A zap uses apps, which represent the actual services you want to connect to. In this case, Jira and Slack. Of course, behind the scenes apps call the actual APIs, but Zapier hides this complexity from users.

New to Zapier? If you don’t currently have a Zapier account, set one up and create up to 5 zaps for free.

Creating a zap

So let’s create a zap!

We’ll automate a very important process: to search the popular discussion forum Reddit for any new parrot themed posts. Then send them directly to me via Gmail, for my viewing pleasure.

From the Zapier dashboard, click the big, unmissable Create Zap button.

First, configure the trigger. That’s something that happens to cause this zap to execute. For example, someone posting a nice parrot picture to Reddit.

A trigger is normally associated with an app, in our case Reddit.

Each app has its own specific events you can use in the trigger. An event roughly corresponds to an API call. Zapier intermittently polls the event to look for new data.

For our Reddit trigger, we’ll use New Hot Post in Subreddit.

So when a new post appears, this trigger will fire. We’ll configure the event shortly so it only triggers for the all-important parrot posts!

Now chose an account, which starts an OAuth 2 authentication flow to log into the service and grant Zapier access to your deepest and darkest secrets.

In the next step, any configuration options that the event offers can be set. For us, thats specifying the parrots topic.

Finally, let’s test the trigger.

Having successfully made the relevant request to Reddit, Zapier brings back some sample Reddit posts.

This one looks interesting (if you’re into parrots).

The next step in creating a zap is to create an action. This uses data from the trigger, and interacts with another app in some way.

For us, we’ll choose everyone’s favourite email service, Gmail.

There’s another authentication flow to run through. But now it’s the fun bit.

Fill in the details of the email. You can either use hard-coded values or use data from the trigger.

For example, here I’m setting the email subject, combining some hard-coded text with some text from the trigger.

The sample data from the trigger shown above (Baby wet chicken…) is just an example. When this zap fires for real, it will use the latest data from Reddit.

Click the Test button to test the action, which results in an email sent to my inbox, based on the sample Reddit post. Amazing stuff!

Finally, give the zap a name and publish it.

Now I’ll sit back, relax, and wait for my inbox to fill with beautiful birds!

---

Setting up zaps like this is straightforward. Yeah, it’s even possible for non-developers. 

But now let’s re-engage our developer brains, and figure out how to have our own apps show up in Zapier. Or in other words, let’s create a Zapier integration.

Create a Zapier integration for your API

A Zapier integration is a Node.js code package, published to Zapier, which it uses to create an app. In the UI, you can then use the app within a zap to connect to your service, via its REST API.

Integrations can be private for only you to use, or public to let anyone connect to your service.

Behind each app (Reddit, Gmail, etc.) on Zapier is an integration which developers at some point built, and most likely update as APIs change.

An integration consists of specifying 3 main things:

1. what triggers and actions are available and how they interact with your API
2. how user configure the triggers and actions in the Zapier UI e.g. fields, descriptions, data types
3. the authentication mechanism

Relating integrations to apps and zaps, we can get a full developer’s view of the Zapier ecosystem.

Getting started with integrations

The Zapier team have thought through the integration setup process quite carefully, offering 2 options:

• a web interface setup for simpler APIs
• a pure code setup for more complex integrations

For developers, I recommend the code-based approach so you can use familiar tools like version control, testing, and your favourite IDE. 

But actually, even if you start creating an integration in the UI, you can later convert it to code using the Zapier command line interface (CLI). This can be a good way to get started, and in fact is exactly what we’ll do.

An example integration

OK. I have an annoying problem that needs fixing.

Whenever I receive a payment from Stripe, I have to manually create a bill in my bookkeeping software to record the processing fees. Automating this would save a lot of time.

Since there’s no Zapier app which does this right now, we’ll create a new integration.

Fortunately, the bookkeeping software, FreeAgent, has a nice JSON REST API to create bills.

POST https://api.freeagent.com/v2/bills

It uses OAuth 2 authentication, which is a kind of handshake to securely connect two services.

Let’s explore creating an integration, first in the UI, then in code.

Creating an integration in the Zapier UI

In the Zapier developer portal, click Start a Zapier integration (see image above). Add some required basic info.

We’ll imaginatively call this integration Example integration, then hit Create.

Now setup authentication. There are different options to choose depending on your API, including API Key, Basic Auth, Digest Auth, and Session Auth. Yep, all the auths.

But we’ll go with OAuth 2, and setup the following required fields:

• client ID
• client secret
• authorization URL
• access token URLs

Now select Sign in to test the authentication. It forwards you to the API’s OAuth 2 endpoint to login and approve, just like we did for Reddit earlier.

The fact that this works proves we’ve setup the authentication part of the integration correctly. Once the integration is published, users will be able to log into their own FreeAgent account within a zap

Next, configure an action, which is responsible for actually creating the bill through the API.

This involves setting up the form to be shown in the Zapier UI, whenever someone uses this integration within a zap.

Integration vs. app vs. zap: note that what we’re doing here is creating the integration. Once pushed to Zapier, this will create an app, which we will use within a zap to interact with FreeAgent.

In the API tab of the action setup screen, we set the all-important HTTP request URL and method.

Zapier attempts to create a request body based on the form we just setup. Since it assumes simple key/value pairs, this might not work.

OK, it almost definitely won’t work.

Provide some sample data to test the request.

If it fails, you can get greater control of the request body by clicking Switch to code mode.

Note that this is different from the full dev CLI environment we’ll explore shortly. This is just a way to set the JSON body using code, but still from within the Zapier UI.

Format the JSON request, as required by the API. In our case, that’s to include a JSON bill key at the top level, and a further bill_items key.

{
   "bill":{
      "contact":"`https://api.sandbox.freeagent.com/v2/contacts/${bundle.inputData.contact_id}`",
      "reference":"bundle.inputData.reference",
      "dated_on":"2022-9-30",
      "due_on":"2022-9-30",
      "bill_items":[
         {
            "category":"`https://api.sandbox.freeagent.com/v2/categories/${bundle.inputData.category_id}`",
            "total_value":"bundle.inputData.total_value"
         }
      ]
   }
}

If you setup the request correctly, on retesting you’ll get a Request Successful message.

This means we’ve setup the action correctly within the integration. Later, once the integration is published, users will be able to configure an action to create a bill, from within a zap.

But now that we’re writing code, wouldn’t you rather switch to a proper development environment?

Converting to a Node.js application

Zapier makes converting the UI-based integration into a local Node.js application really easy.

Just install the zapier CLI.

npm install -g zapier-platform-cli

Then run convert to generate a project in a specific directory.

zapier convert <integration-id> --version=<version> <path>

Open the project in your IDE of choice. Visual Studio Code is a good bet for Node.js. You can now work on this like a normal application.

Of particular interest, the following files were generated:

• authentication.js for the OAuth 2 authentication setup earlier in the UI
• creates/create_bill.js for the create bill action setup earlier in the UI
• test/creates/create_bill.js the corresponding create bill test case
• index.js the main entry point to the application, referencing creates/create_bill.js
• package.json the Node.js file defines the dependent packages e.g. zapier-platform-core

Within the implementation file creates/create_bill.js, you can add any required custom logic to happen before or after the API request is made.

const perform = async (z, bundle) => {
  const options = {
    url: 'https://api.sandbox.freeagent.com/v2/bills',
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Accept: 'application/json',
      Authorization: `Bearer ${bundle.authData.access_token}`,
    },
    params: {},
    body: {
      bill: {
        contact: `https://api.sandbox.freeagent.com/v2/contacts/${bundle.inputData.contact_id}`,
        reference: bundle.inputData.reference,
        dated_on: '2022-9-30',
        due_on: '2022-9-30',
        bill_items: [
          {
            category: `https://api.sandbox.freeagent.com/v2/categories/${bundle.inputData.category_id}`,
            total_value: bundle.inputData.total_value,
          },
        ],
      },
    },
  };

  return z.request(options).then((response) => {
    response.throwForStatus();
    const results = response.json;

    // You can do any parsing you need for results here before returning them

    return results;
  });
};

Add any new triggers or actions by creating a similar file, then configuring index.js accordingly.

const authentication = require('./authentication');
const createBillCreate = require('./creates/create_bill.js');

module.exports = {
  version: require('./package.json').version,
  platformVersion: require('zapier-platform-core').version,
  authentication: authentication,
  creates: { [createBillCreate.key]: createBillCreate },
};

To understand what elements you can pass here (and what creates even means), I recommend the triggers/searches/creates section of the Zapier documentation.

The Zapier CLI convert command even generated an API test case, test/creates/create_bill.js. By default, this hits the real URL, so I prefer instead to mock the response using the nock framework.

  it('should create bill', async () => {
    const bundle = {
      authData: {
        access_token: process.env.ACCESS_TOKEN,
        refresh_token: process.env.REFRESH_TOKEN,
      },

      inputData: {
        contact_id: '108572',
        reference: 'Joe Bloggs',
        category_id: '270',
        total_value: '400',
      },
    };

    nock('https://api.sandbox.freeagent.com/v2')
      .post('/bills')
      .reply(200, createBillResponse);

    const result = await appTester(
      App.creates['create_bill'].operation.perform,
      bundle
    );
    result.should.not.be.an.Array();
  });

Once you’re done, run:

• npm install to install packages as defined by package.json
• zapier test to run tests and other validations
• zapier push to deploy to the Zapier servers

Once complete, you’ll notice that within the developer portal you now have restricted write access.

That’s because we’re now maintaining this integration in developer rather than UI mode.

Let’s try out our new integration within a zap.

Use your new app in a zap

Create a zap, skipping the trigger setup you saw earlier, and jumping straight to the action.

Now we have an option to select the new Example integration integration, with version 1.0.1.

What version? Zapier automatically increments the patch version to 1.0.1 when you run zapier convert. Feel free to change the version any time within package.json.

Next, select the event. In our case there’s only one option, Create Bill.

Now run through the authentication flow.

Next, configure values for the fields we setup earlier. I’ll just enter some hard-coded data, but normally you’ll also use data from a trigger. For example, transaction data from Stripe or PayPal.

Click Test to test the action, and it shows the success API response body.

Double-checking within my FreeAgent account shows that the bill was indeed created, all using our Zapier integration. Awesome!

Once you’re happy everything is working, you have 2 options:

1. leave the integration private and use it only within your own zaps
2. follow Zapier’s launch steps to publish it, for anyone to use in their own zaps in new and interesting ways

Final thoughts

Of course, integrations can do a lot more, like creating dynamic fields backed by an API to make configuration even simpler. But at least now you know the basics of what’s involved. 

Does Zapier sounds interesting to you? Is there an integration you’d like to create? Let me know your thoughts down below in the comments.

Likewise, if there are any further technical details you’d like to know, I’d be glad to help.

Resources

• Zapier integration documentation
• accompanying YouTube video