ActiveCampaign Integration

🌐 Overview

ActiveCampaign integration providing access to CRM data including contacts, deals, and accounts through API key authentication. Supports pagination, filtering, and ordering for flexible data retrieval.

Provider: ActiveCampaign (https://www.activecampaign.com)
API Version: v3
Integration Type: API Key authentication with account-specific base URLs

📚 Documentation Structure

This integration is organized into the following sections:

1. Authentication - API key setup and credential management
2. CRM Data Export - Contacts, deals, and accounts export with pagination

🔧 Features

• ✅ API Key Authentication: Simple credential-based authentication
• ✅ Contact Management: Export all contact data with custom fields
• ✅ Deal Management: Retrieve deals with pipeline stages
• ✅ Account Management: Fetch account/organization data
• ✅ Pagination: Page-based pagination with configurable limits
• ✅ Filtering: Field-based filtering for targeted queries
• ✅ Ordering: Multi-field sorting (ASC/DESC)
• ✅ Sub-account Support: Works with DashClicks sub-accounts

📊 Architecture

Frontend Request
       ↓
API Key Validation
       ↓
Credential Storage (MongoDB)
       ↓
Account-Specific Base URL
       ↓
ActiveCampaign API v3
       ↓
Contacts / Deals / Accounts

🗄️ MongoDB Collections

📚 Detailed Schema: See Database Collections Documentation

integrations-activecampaign-keys

Purpose: Store API keys and account-specific base URLs

Key Fields:

• api_key (String) - ActiveCampaign API key
• base_url (String) - Account-specific API base URL
• account_id (String) - DashClicks account ID
• owner (String) - DashClicks user ID
• workspace_id (String) - DashClicks workspace ID

Indexes:

• { account_id: 1, owner: 1 } (unique) - Primary lookup

📁 Directory Structure

Source Code Location:

external/Integrations/ActiveCampaign/
├── Controllers/
│   ├── auth.js          # API key management
│   └── export.js        # CRM data export
├── Models/
│   └── keys.js          # Database operations
├── Providers/
│   └── api.js           # ActiveCampaign API wrapper
├── Routes/
│   ├── auth.js          # Auth endpoints
│   └── export.js        # Export endpoints
└── index.js             # Route registration

🚀 Quick Start

1. Configure Environment Variables

ACTIVECAMPAIGN_API_VERSION=/api/3

2. Obtain API Credentials

From ActiveCampaign dashboard:

1. Go to Settings → Developer
2. Copy API URL (base URL) - e.g., https://dashclicks83379.api-us1.com
3. Copy API Key

3. Save Credentials

POST /v1/integrations/activecampaign/auth
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "api_key": "your_api_key_here",
  "base_url": "https://dashclicks83379.api-us1.com"
}

4. Export Contacts

GET /v1/integrations/activecampaign/export/contacts?page=1&limit=100
Authorization: Bearer {jwt_token}

5. Export Deals

GET /v1/integrations/activecampaign/export/deals?page=1&limit=50
Authorization: Bearer {jwt_token}

6. Export Accounts

GET /v1/integrations/activecampaign/export/accounts?page=1&limit=50
Authorization: Bearer {jwt_token}

📖 API Endpoints Summary

Method	Endpoint	Description
POST	/auth	Save API key and base URL
DELETE	/auth	Delete stored credentials
GET	/export/contacts	Export contact data
GET	/export/deals	Export deal data
GET	/export/accounts	Export account data

🔑 Base URL Structure

Each ActiveCampaign account has a unique base URL:

https://{account_name}.api-{region}.com

Examples:

• https://dashclicks83379.api-us1.com - US region
• https://mycompany.api-us1.com - US region
• https://example.api-eu1.com - EU region

All API requests use this base URL with the API version path:

{base_url}/api/3/{endpoint}

⚙️ Query Parameters

Pagination

Parameter	Type	Description	Default
page	Integer	Page number	1
limit	Integer	Records per page	20

Example:

GET /export/contacts?page=2&limit=50

Ordering

Parameter	Type	Description
orders[field]	String	Sort direction (ASC/DESC)

Example:

GET /export/accounts?orders[name]=DESC

Filtering

Parameter	Type	Description
filters[field]	String	Filter value

Example:

GET /export/accounts?filters[name]=Acme Corporation

Combined Example

GET /export/contacts?page=1&limit=100&orders[email]=ASC&filters[firstName]=John

📊 Response Format

All export endpoints return standardized responses:

{
  "success": true,
  "message": "SUCCESS",
  "data": [...],
  "pagination": {
    "page": "1",
    "limit": "50",
    "total": "150",
    "next_page": 2,
    "prev_page": null
  }
}

🔒 Authentication

API key authentication with validation:

1. API Key Required: All endpoints require valid API key
2. Base URL Required: Account-specific base URL must be stored
3. JWT Auth: DashClicks JWT token required for all requests
4. Single Connection: One set of credentials per user/account combination

⚠️ Important Notes

• 🔑 API Key Security: Keys stored in MongoDB, should be encrypted at rest
• 🌍 Region-Specific URLs: Each account has unique base URL
• 📊 Pagination: ActiveCampaign uses page-based pagination
• 🔍 Validation: API key validated on save by making test request
• 👤 Single Connection: One credential set per user/account pair
• ⚡ Performance: Large exports (10,000+ records) may take several seconds

🔗 Related Documentation

• ActiveCampaign API Documentation
• Contacts API
• Deals API
• Accounts API
• Pagination Reference

🎯 Use Cases

Initial CRM Sync

Export all contacts, deals, and accounts for first-time sync to DashClicks.

Incremental Updates

Use pagination to fetch recent updates or specific data sets.

Filtered Queries

Apply filters to export specific segments (e.g., contacts from specific lists).

Sorted Data

Order results by creation date, name, or custom fields.

🐛 Troubleshooting

"Invalid base_url or api_key"

Credentials are incorrect. Verify from ActiveCampaign dashboard.

"Record already exist"

Credentials already saved. Delete first, then re-save.

"Unauthorised Access"

No credentials found for user/account. Save credentials first.

📈 Performance Considerations

• Rate Limits: ActiveCampaign limits vary by plan (typically 5-10 requests/second)
• Page Size: Optimal page size is 100-250 records
• Filtering: Reduces response size and improves performance
• Caching: Consider caching frequently accessed data
• Batch Processing: For large exports, use queue-based processing