ActiveCampaign is a multi-purpose cloud software platform for small-to-mid-sized businesses. The platform offers solutions for customer experience automation, including email marketing, marketing automation, sales automation, and CRM. If your product needs to interact with CRM data or any related automation tools, an integration with ActiveCampaign is essential.

Building an ActiveCampaign integration is not a walk in the park due to the platform's diverse features and varied functionalities. Fortunately, we’ve already gone through the headache of building and maintaining a complex native ActiveCampaign integration. In this guide, we share all the wisdom and gotchas we’ve picked up over the years.

If you’re unfamiliar with what native integrations are in the first place, you can reference our previous blog post aptly titled what are native integrations?

As a side note, I’ll be using the Vessel SDK to build this integration so I don’t have to worry about setting up Auth or handling any ActiveCampaign API quirks. If you want to follow along you can sign up here.

If you don’t want to use Vessel, no worries, I’ve kept this guide as generic as possible and it will be useful regardless of how you decide to build your native ActiveCampaign integration.

Getting Setup For your ActiveCampaign Integration

Before you dive into writing code for your ActiveCampaign integration, there are a few logistical things you’ll want to get out of the way.

Create a Sandbox Account

First, you’ll need access to a developer or sandbox account. ActiveCampaign provides a free sandbox account that allows you to test your integration without affecting real customer data and also comes with some fake test data.

🔗 Sandbox Developer Account

Create an ActiveCampaign API Key

Once you have a developer account, you'll need to get an API key. The API key is used to authenticate your integration with ActiveCampaign's API and it’s what lets us make API calls. To get your API key, go to Settings > Developer

The ActiveCampaign API at a Glance

Authentication

Authentication is the first step in making API calls to ActiveCampaign. To authenticate your integration, you'll need to include your API key in the request headers. Here's an example of how to authenticate using the ActiveCampaign API key:

const apiKey = "YOUR_API_KEY";

// Make API call with authentication
const url = `https://${account}.api-us1.com/api/3/contacts`
const response = await fetch(url, {
  method: "GET",
  headers: {
    "Api-Token": apiKey
  }
});

Make sure to replace YOUR_API_KEY with your actual ActiveCampaign API key.

Making an API Call

Now that you’re able to authenticate your user, you can begin making API calls to their CRM 🥳! In this section, we’ll explore how to read and write to the ActiveCampaign API in real-time.

Reading From the API

Reading from the ActiveCampaign API is relatively straightforward, however, here are a few things to keep in mind:

• Filtering: ActiveCampaign supports filtering by various parameters, such as email, tags, and custom fields. Make sure to read the API documentation to understand all the available filtering options.
• Account Domain: All API calls need to be prefixed by the account domain which your customer can find in their ActiveCampaign account. As of this writing, there is no way to get this information without asking your customer for it.
• Side Loading: You can load multiple related resources when you fetch a single resource by using side loading.

Through ActiveCampaign API

Here's an example API call for reading contacts using the ActiveCampaign API:

const url = `https://${acDomain}.api-us1.com/api/3/contacts`
const response = await fetch(url, {
  headers: { 
    'Api-Token': apiKey  
   }
});

const data = await response.json();

With Vessel

If you're using the Vessel SDK, you can simplify the process of making API calls to the ActiveCampaign API. Here's an example of how to use the Vessel SDK to fetch a list of contacts:

import Vessel from '@vesselapi/sdk';

const vessel = Vessel({ 
  apiKey: "YOUR_API_KEY",
  accessToken: "YOUR_CUSTOMERS_ACCESS_TOKEN"
});

// Fetch a list
const response = await vessel.unifications.marketingAutomation.contacts.list();

console.log(response);

Note that we can use the unified API for this call so that we don’t have to rebuild this flow if we want to support other marketing automation tools like Mailchimp.

Writing to the API

When writing to the ActiveCampaign, make sure you handle errors correctly and also follow best practices like sleeping for 1000 milliseconds before retrying.

Through ActiveCampaign API

Here's an example API call for creating a contact using the ActiveCampaign API:

const url = `https://${acDomain}.api-us1.com/api/3/contacts`;
const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Api-Token': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    contact: {
       email: 'test@example.com',
       firstName: 'John',
       lastName: 'Doe'
     }
  })
});

const data = await response.json();

With Vessel

If you're using the Vessel SDK, you can simplify the process of making API calls to the Mailchimp API. Here's an example of how to use the Vessel SDK to add a new subscriber:

import Vessel from '@vesselapi/sdk';

const vessel = Vessel({
  apiKey: process.env.API_KEY,
  accessToken: "YOUR_CUSTOMERS_ACCESS_TOKEN"
})

const response = await vessel.unifications.marketingAutomation.contacts.create({
  email: 'test@example.com',
  firstName: 'John',
  lastName: 'Doe'
});

Again, we can use the unified API to avoid having to build this out for multiple marketing automation integrations.

Closing Thoughts

App Studio

While using the ActiveCampaign API offers the most flexibility and is more maintainable if you want to support more integrations, you can also build an ActiveCampaign integration through their App Studio builder.

About Us

Hopefully, you found this article helpful for building out your native ActiveCampaign integration. I know I certainly wish something like this existed when we built out our ActiveCampaign integration.

If you decided to give Vessel a spin while following this tutorial, thank you. If you have any feedback while using the SDK, don’t hesitate to reach out at support@vessel.dev. We’re a team of engineers at heart and take every piece of feedback extremely seriously.

if you’re curious to learn more about why we started Vessel and how we view the future of customer-facing integrations, you can read more in our “what are native integration platforms” posts.

On that note, if you ever have any questions about building an ActiveCampaign integration while you’re going through this tutorial, regardless of if you decide to use Vessel, don’t hesitate to reach out at zach@vessel.dev and I’ll be more than happy to personally help.