A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The ActiveCampaign API is how an app or AI agent works with a marketing and CRM account: adding and updating contacts, applying tags, subscribing people to lists, creating deals in the pipeline, and enrolling contacts in automations. Access is granted through an account API key sent in a header, and that key has no granular scopes, so it reaches everything its account can read or write. A state change can be pushed to a registered webhook, like a contact subscribing or a tag being added.
How an app or AI agent connects to ActiveCampaign determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes ActiveCampaign tools to agents, and each is governed by the key or login behind it.
The REST API takes JSON request bodies, returns JSON, and pages through lists with limit and offset, at an account-specific base URL of the form https://{youraccountname}.api-us1.com/api/3. The exact host must be read from the account's Developer settings rather than assumed. A call authenticates with the account's API key in the Api-Token header. All v3 endpoints are supported except events and site tracking.
ActiveCampaign POSTs an event to an HTTPS URL registered for chosen event types, so an integration learns about activity without polling. Events cover contact, list, deal, campaign, email, and SMS activity, and each event names the source that triggered it (public, admin, api, or system). Webhooks are managed through the /api/3/webhooks endpoint.
A hosted Model Context Protocol server exposes ActiveCampaign tools to AI agents and MCP clients like Claude, ChatGPT, and Cursor. Each account gets its own Remote MCP URL from the Developer settings, and the client authenticates through OAuth to connect the account. The tools cover reading and updating contacts, managing lists, tags, and custom fields, retrieving campaign and account insights, and triggering automations.
Every request authenticates with the account's API key, sent in the Api-Token header. The key is found in the account's Settings under the Developer tab, and each user in the account has their own unique key. ActiveCampaign has no granular API scopes, so a key reaches everything its account can read or write. The key must be kept server-side and never exposed in client code.
Connecting the Remote MCP server uses OAuth: the client is given the account-specific Remote MCP URL and is guided through an OAuth login to authorize access to the account. This route is for MCP clients rather than direct REST calls, and it represents the connected account.
The ActiveCampaign API is split into areas an agent can act on, like contacts, lists, tags, deals, custom fields, campaigns, automations, and CRM accounts. Each area has its own methods, and the key behind a call reaches every area its account can, because access is granted at the account level rather than per area.
Create a contact, retrieve one, list and search the whole base, update a contact, upsert by email, bulk import, and delete a contact.
Create a list, retrieve one, list all of them, and subscribe or unsubscribe a contact from a list.
List all tags, create a tag, apply a tag to a contact, and remove a tag from a contact.
Create a deal, retrieve one, list all deals, and update a deal in the CRM pipeline.
List custom contact fields, retrieve one, and create a new custom field definition.
Create a campaign that sends email to contacts.
List all automations, add a contact to an automation, list the automations a contact is in, and remove a contact from one.
List all CRM accounts and create a new account record for a business.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ContactsCreate a contact, retrieve one, list and search the whole base, update a contact, upsert by email, bulk import, and delete a contact.7 | ||||||
| POST | /api/3/contacts | Create a new contact. | write | contacts: write | Current | |
ActiveCampaign has no granular API scopes; the Api-Token reaches everything the account can. A duplicate email returns a validation error. Acts oncontact Permission (capability) contacts: writeVersionAvailable since the API’s base version Webhook event subscribeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/3/contacts/:id | Retrieve an existing contact, including its list memberships and automations. | read | contacts: read | Current | |
Read-only. No granular scope; the Api-Token sees every contact the account holds. Acts oncontact Permission (capability) contacts: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/3/contacts | List, search, and filter contacts by email, list, tag, automation, and other criteria. | read | contacts: read | Current | |
Read-only. Paginates with limit and offset, defaulting to 20 and capped at 100. Acts oncontact Permission (capability) contacts: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/3/contacts/:id | Update an existing contact's details and field values. | write | contacts: write | Current | |
A core write. No granular scope; the Api-Token can update any contact. Acts oncontact Permission (capability) contacts: writeVersionAvailable since the API’s base version Webhook event updateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/3/contact/sync | Create or update a contact in one call, matched on email (an upsert). | write | contacts: write | Current | |
Email is the identifying key: a match updates the existing contact, otherwise a new one is created. Acts oncontact Permission (capability) contacts: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/3/import/bulk_import | Bulk import many contacts in a single request, with list subscribe and unsubscribe flags. | write | contacts: write | Current | |
Imports run asynchronously and can subscribe contacts to lists in the same call. Acts oncontact Permission (capability) contacts: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/3/contacts/:id | Permanently delete a contact. | write | contacts: write | Current | |
Irreversible; removes the contact and its associated history. Acts oncontact Permission (capability) contacts: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ListsCreate a list, retrieve one, list all of them, and subscribe or unsubscribe a contact from a list.4 | ||||||
| POST | /api/3/lists | Create a new list. | write | lists: write | Current | |
A core write. No granular scope; the Api-Token can manage any list. Acts onlist Permission (capability) lists: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/3/lists/:id | Retrieve a single list and its settings. | read | lists: read | Current | |
Read-only. Acts onlist Permission (capability) lists: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/3/lists | Retrieve all lists in the account. | read | lists: read | Current | |
Read-only. Paginates with limit and offset, defaulting to 20. Acts onlist Permission (capability) lists: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/3/contactLists | Subscribe a contact to a list or unsubscribe a contact from a list. | write | lists: write | Current | |
Status 1 subscribes and status 2 unsubscribes; re-subscribing a manually unsubscribed contact is possible. Acts oncontactList Permission (capability) lists: writeVersionAvailable since the API’s base version Webhook event subscribeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TagsList all tags, create a tag, apply a tag to a contact, and remove a tag from a contact.4 | ||||||
| GET | /api/3/tags | List all tags in the account. | read | tags: read | Current | |
Read-only. Acts ontag Permission (capability) tags: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/3/tags | Create a new tag. | write | tags: write | Current | |
Creates the tag definition; applying it to a contact is a separate call. Acts ontag Permission (capability) tags: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/3/contactTags | Apply an existing tag to an existing contact. | write | tags: write | Current | |
Creates the association between a tag and a contact, which can move the contact in or out of automations. Acts oncontactTag Permission (capability) tags: writeVersionAvailable since the API’s base version Webhook event contact_tag_addedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/3/contactTags/:id | Remove a tag from a contact by deleting the contact-tag association. | write | tags: write | Current | |
Removes the association, not the tag itself. The association id comes from a contact's contactTags. Acts oncontactTag Permission (capability) tags: writeVersionAvailable since the API’s base version Webhook event contact_tag_removedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Deals (CRM)Create a deal, retrieve one, list all deals, and update a deal in the CRM pipeline.4 | ||||||
| POST | /api/3/deals | Create a new deal in the CRM. | write | deals: write | Current | |
A core CRM write. Sets fields like contact, value, owner, stage, and status. Acts ondeal Permission (capability) deals: writeVersionAvailable since the API’s base version Webhook event deal_addRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/3/deals/:id | Retrieve an existing deal. | read | deals: read | Current | |
Read-only. Acts ondeal Permission (capability) deals: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/3/deals | List all deals in the CRM. | read | deals: read | Current | |
Read-only. Paginates with limit and offset. Acts ondeal Permission (capability) deals: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/3/deals/:id | Update an existing deal's properties. | write | deals: write | Current | |
Can change contact, account, currency, group, owner, stage, status, title, value, and custom fields. Acts ondeal Permission (capability) deals: writeVersionAvailable since the API’s base version Webhook event deal_updateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Custom fieldsList custom contact fields, retrieve one, and create a new custom field definition.3 | ||||||
| GET | /api/3/fields | List all custom contact fields. | read | fields: read | Current | |
Read-only. Acts onfield Permission (capability) fields: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/3/fields/:id | Retrieve a single custom contact field by id. | read | fields: read | Current | |
Read-only. Acts onfield Permission (capability) fields: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/3/fields | Create a new custom contact field. | write | fields: write | Current | |
Defines a field used across every contact in the account. Acts onfield Permission (capability) fields: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CampaignsCreate a campaign that sends email to contacts.1 | ||||||
| POST | /api/3/campaign | Create a campaign (the path is singular, /campaign). | write | campaigns: write | Current | |
Requires a name and type. Creates an outbound email campaign that can reach real recipients. Acts oncampaign Permission (capability) campaigns: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AutomationsList all automations, add a contact to an automation, list the automations a contact is in, and remove a contact from one.4 | ||||||
| GET | /api/3/automations | List all automations with their status and related links. | read | automations: read | Current | |
Read-only. Acts onautomation Permission (capability) automations: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/3/contactAutomations | Add a contact to an automation, enrolling them in the workflow. | write | automations: write | Current | |
Enrolls a contact in an automated workflow that may send messages or apply tags. Acts oncontactAutomation Permission (capability) automations: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/3/contactAutomations | List the automations contacts are in. | read | automations: read | Current | |
Read-only. Acts oncontactAutomation Permission (capability) automations: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/3/contactAutomations/:id | Remove a contact from an automation. | write | automations: write | Current | |
Ends the contact's enrollment in that workflow. Acts oncontactAutomation Permission (capability) automations: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Accounts (CRM)List all CRM accounts and create a new account record for a business.2 | ||||||
| GET | /api/3/accounts | List all CRM accounts, with details like name, contact count, and deal count. | read | accounts: read | Current | |
Read-only. Acts onaccount Permission (capability) accounts: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/3/accounts | Create a new CRM account record for a business. | write | accounts: write | Current | |
A core CRM write. Acts onaccount Permission (capability) accounts: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ActiveCampaign can notify an app or AI agent when something happens in an account, like a contact subscribing, a tag being added, or a deal moving stage, instead of the app repeatedly asking. ActiveCampaign posts the event to a webhook URL registered for the chosen event types.
| Event | What it signals | Triggered by |
|---|---|---|
subscribe | A contact subscribed to a list. | /api/3/contacts/api/3/contactLists |
unsubscribe | A contact unsubscribed from a list. | /api/3/contactLists |
update | A contact's details were updated. | /api/3/contacts/:id |
contact_tag_added | A tag was applied to a contact. | /api/3/contactTags |
contact_tag_removed | A tag was removed from a contact. | /api/3/contactTags/:id |
deal_add | A new deal was created in the CRM. | /api/3/deals |
deal_update | An existing deal changed, like its stage, owner, or value. | /api/3/deals/:id |
ActiveCampaign limits how fast an app or AI agent can call, by a request rate measured per second across the whole account rather than per method.
ActiveCampaign meters requests by rate across the whole account, not by a per-method cost. An account allows 5 requests per second, reported on each response through a RateLimit-Limit header (for example RateLimit-Limit: 5) and a RateLimit-Remaining header. Going over returns HTTP 429 Too Many Requests with a Retry-After header (for example Retry-After: 30) naming how long to wait. Accounts with high demand can arrange a custom rate limit with ActiveCampaign.
List endpoints page with two query parameters: limit sets the page size, defaulting to 20 and capped at 100, and offset is a zero-based starting index. To walk a full collection, increment offset by limit each request; the response meta.total field gives the size of the whole collection. Results can be ordered with an orders parameter and narrowed with a filters parameter, whose match behaviour (equals or contains) varies by endpoint.
A list endpoint returns at most 100 records per page, the maximum value of limit. Larger reads are made by paging through with offset rather than raising the cap.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | No valid API key was supplied in the Api-Token header. | Send a valid key from the account's Developer tab, and confirm the request uses the account-specific base URL. |
| 403 | Forbidden | The key is valid but the request is not permitted, for example the wrong account host. | Confirm the API URL from the user's Developer tab and that the key belongs to that account. |
| 404 | Not Found | The requested resource does not exist or is not visible to this account. | Verify the resource id and that it belongs to the same account. |
| 422 | Unprocessable Entity | Validation failed, for example a missing required field or a duplicate contact email. | Read the returned error messages, fix the parameters, and resend. |
| 429 | Too Many Requests | The account exceeded its rate of 5 requests per second. The response carries a Retry-After header. | Back off and retry after the period named in the Retry-After header, and smooth the request rate. |
ActiveCampaign runs a single current version of its REST API, version 3, and ships a dated developer changelog for new endpoints and behaviour changes rather than minting new version numbers.
Version 3 is the current REST API, signalled by the /api/3 path. It is structured around REST, HTTP, and JSON, authenticates with the Api-Token header, and supports every documented endpoint except events and site tracking. ActiveCampaign does not pin a version per account; new endpoints and behaviour changes are published in a dated developer changelog.
The original v1 API is deprecated in favour of v3. New integrations use v3, and the v1 surface is no longer recommended.
There is one current version to call, so an integration tracks the changelog rather than pinning a version.
ActiveCampaign developer changelog ↗Bollard AI sits between a team's AI agents and ActiveCampaign. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.