Getting started overview

Integrating with the ActiveCampaign API involves a sequence of steps designed to ensure secure and functional access. This guide focuses on the foundational process, beginning with account creation, securing API credentials, and executing a basic API request to verify your setup. ActiveCampaign's API is RESTful, utilizing standard HTTP methods and JSON for data exchange. Authentication relies on an API key, which must be included in each request to authorize access to your account's resources.

The primary goal of this guide is to enable you to successfully make your first authenticated call to the ActiveCampaign API. This initial success confirms that your API credentials are correctly configured and that your development environment can communicate with ActiveCampaign's servers. Subsequent development can then build upon this established connection to implement more complex marketing automation or CRM integrations.

Quick Reference Steps

Step What to Do Where
1. Account Setup Sign up for an ActiveCampaign account (paid plan required for API access). ActiveCampaign Pricing Page
2. API Key Retrieval Locate your API URL and API Key within your ActiveCampaign account settings. ActiveCampaign Admin > Settings > Developer
3. Environment Setup Choose a programming language or an HTTP client (e.g., cURL, Postman). Your local development environment
4. First Request Construct and execute a simple GET request to an ActiveCampaign API endpoint. Your chosen HTTP client or code editor
5. Verify Response Check for a successful HTTP status code (e.g., 200 OK) and expected data. HTTP client or console output

Create an account and get keys

To access the ActiveCampaign API, you must have an active paid ActiveCampaign account. ActiveCampaign does not offer a free tier that includes API access, so a subscription to one of their paid plans (starting with the Lite plan) is a prerequisite. You can review the available plans and sign up on the ActiveCampaign pricing page.

Account Creation

  1. Navigate to the ActiveCampaign website.
  2. Select a suitable plan (e.g., Lite, Plus, Professional, Enterprise) and complete the signup process.
  3. Follow the on-screen prompts to set up your account and initial preferences.

Retrieving Your API URL and Key

Once your ActiveCampaign account is active, your API credentials can be found within the administrative interface. These credentials consist of an API URL and an API Key, both of which are essential for authenticating your requests.

  1. Log in to your ActiveCampaign account.
  2. In the left-hand navigation menu, click Settings (gear icon).
  3. From the Settings menu, select Developer.
  4. On the Developer page, you will find your API URL and API Key. Copy both of these values. They are sensitive credentials and should be stored securely, such as in environment variables, and not hardcoded directly into your application's source code.

The API URL will typically be in the format https://YOUR_ACCOUNT_NAME.api-us1.com, and the API Key will be a long alphanumeric string. Both are required for all authenticated API calls.

Your first request

After obtaining your API URL and API Key, you can proceed to make your first authenticated request. A common initial request is to retrieve a list of contacts, which confirms that your authentication is set up correctly and that you can communicate with the API.

Using cURL for a GET Request

cURL is a command-line tool and library for transferring data with URLs. It is pre-installed on most Unix-like operating systems and is a straightforward way to test API endpoints. This example demonstrates how to fetch a list of contacts.

Replace YOUR_API_URL with your actual ActiveCampaign API URL and YOUR_API_KEY with your API Key.

curl -X GET \
  'YOUR_API_URL/api/3/contacts' \
  -H 'Api-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json'

Explanation of the cURL command:

  • -X GET: Specifies the HTTP method as GET.
  • 'YOUR_API_URL/api/3/contacts': This is the endpoint for retrieving contacts. The /api/3/ prefix indicates the API version.
  • -H 'Api-Token: YOUR_API_KEY': Sets the Api-Token header, which is how ActiveCampaign authenticates your request.
  • -H 'Content-Type: application/json': Specifies that the request body (though empty for a GET) and expected response will be JSON format.

Expected Response

A successful response for retrieving contacts will typically return an HTTP status code of 200 OK and a JSON object containing an array of contact objects. If your account has no contacts, the contacts array might be empty.

{
  "contacts": [
    {
      "id": "1",
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe",
      "phone": "",
      "contactUrl": "https://YOUR_ACCOUNT_NAME.activehosted.com/app/contacts/1",
      "organization": "",
      "organizationName": "",
      "segmentio_id": "",
      "tags": [],
      "links": {
        "bounceLogs": "https://YOUR_API_URL/api/3/contacts/1/bounceLogs",
        "contactAutomations": "https://YOUR_API_URL/api/3/contacts/1/contactAutomations",
        "contactData": "https://YOUR_API_URL/api/3/contacts/1/contactData",
        "contactGoals": "https://YOUR_API_URL/api/3/contacts/1/contactGoals",
        "contactLists": "https://YOUR_API_URL/api/3/contacts/1/contactLists",
        "contactTags": "https://YOUR_API_URL/api/3/contacts/1/contactTags",
        "fieldValues": "https://YOUR_API_URL/api/3/contacts/1/fieldValues",
        "geoIps": "https://YOUR_API_URL/api/3/contacts/1/geoIps",
        "notes": "https://YOUR_API_URL/api/3/contacts/1/notes",
        "organization": "https://YOUR_API_URL/api/3/contacts/1/organization",
        "plusappend": "https://YOUR_API_URL/api/3/contacts/1/plusappend",
        "scoreValues": "https://YOUR_API_URL/api/3/contacts/1/scoreValues",
        "tags": "https://YOUR_API_URL/api/3/contacts/1/tags",
        "trackingLogs": "https://YOUR_API_URL/api/3/contacts/1/trackingLogs",
        "dealContacts": "https://YOUR_API_URL/api/3/contacts/1/dealContacts"
      }
    }
  ],
  "meta": {
    "total": "1"
  }
}

If you receive a 401 Unauthorized or 404 Not Found error, double-check your API URL and API Key for accuracy and ensure they are correctly placed in the request headers. The ActiveCampaign API documentation provides further details on error responses.

Using Python for a GET Request

For programmatic interaction, Python with the requests library is a common choice.

import requests
import os

# It's recommended to store sensitive information in environment variables
API_URL = os.environ.get("AC_API_URL")
API_KEY = os.environ.get("AC_API_KEY")

if not API_URL or not API_KEY:
    print("Error: AC_API_URL and AC_API_KEY environment variables not set.")
    exit()

headers = {
    'Api-Token': API_KEY,
    'Content-Type': 'application/json'
}

# Construct the full endpoint URL
endpoint = f"{API_URL}/api/3/contacts"

try:
    response = requests.get(endpoint, headers=headers)
    response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
    data = response.json()
    print("Successfully retrieved contacts:")
    print(data)
except requests.exceptions.HTTPError as e:
    print(f"HTTP error occurred: {e}")
    print(f"Response body: {response.text}")
except requests.exceptions.ConnectionError as e:
    print(f"Connection error occurred: {e}")
except requests.exceptions.Timeout as e:
    print(f"Timeout error occurred: {e}")
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

Before running this Python script, set your environment variables:

export AC_API_URL='https://YOUR_ACCOUNT_NAME.api-us1.com'
export AC_API_KEY='YOUR_API_KEY'

This script will attempt to fetch contacts and print the JSON response, or an error message if the request fails. Using environment variables is a more secure practice than hardcoding credentials, as recommended by security guidelines for API keys, such as those discussed in Google Cloud's API key best practices.

Common next steps

Once you have successfully made your first API call, you can explore various functionalities offered by the ActiveCampaign API:

  • Contact Management: Create, update, or delete contacts. Add contacts to lists, apply tags, or update custom field values. Refer to the Contacts API reference.
  • List and Tag Management: Programmatically manage your contact lists and tags. This is useful for segmenting your audience based on external data or application events.
  • Automation Integration: Trigger automations, add contacts to an automation, or check a contact's status within an automation. This allows you to initiate ActiveCampaign workflows from your custom applications. Refer to the Automations API reference.
  • Campaign Management: Create and send email campaigns, or retrieve campaign performance data.
  • CRM (Deals) Integration: Manage deals, pipelines, and tasks within the ActiveCampaign CRM. This is particularly useful for synchronizing sales activities with your marketing efforts. Refer to the Deals API reference.
  • Webhooks: Set up webhooks to receive real-time notifications from ActiveCampaign when specific events occur (e.g., contact updated, deal created). This enables event-driven integrations. The Webhooks API documentation provides setup instructions.

The ActiveCampaign API Reference serves as the comprehensive source for all available endpoints, request parameters, and response structures.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

  • Verify API URL and Key: Double-check that your API URL and API Key are copied precisely from your ActiveCampaign Developer settings. Even a single incorrect character can cause authentication failures.
  • Check HTTP Headers: Ensure that the Api-Token header is correctly set with your API Key. Also, confirm the Content-Type: application/json header is present, especially for POST/PUT requests.
  • Endpoint Accuracy: Confirm that the API endpoint you are calling (e.g., /api/3/contacts) matches the documentation exactly, including case sensitivity.
  • HTTP Status Codes: Pay close attention to the HTTP status code returned in the API response. Common errors include:
    • 401 Unauthorized: Indicates an issue with your API Key (missing, invalid, or expired).
    • 404 Not Found: Often means the endpoint URL is incorrect or the resource does not exist.
    • 400 Bad Request: Suggests an issue with your request payload or parameters (e.g., missing required fields, incorrect data types).
    • 5xx Server Error: Points to an issue on ActiveCampaign's side. If these persist, check the ActiveCampaign status page or contact support.
  • Review ActiveCampaign API Documentation: The official ActiveCampaign API documentation provides detailed error codes and explanations for each endpoint.
  • Network Connectivity: Ensure your development environment has internet access and is not blocked by a firewall from reaching ActiveCampaign's API servers.
  • CORS Issues: If you are making requests from a web browser (e.g., using JavaScript in a frontend application), you might encounter Cross-Origin Resource Sharing (CORS) errors. For server-side integrations, CORS is typically not an issue.