Skip to main content

API Overview

Updated

Introduction

Version 3 of the API is structured around REST, HTTP, and JSON. API endpoint URLs are organized around resources, such as contacts or deals. It uses HTTP methods for indicating the action to take on a resource, and HTTP status codes for expressing error states. Resources are represented in JSON following a conventional schema.

Base URL

The API is accessed using a base URL that is specific to your account. In the examples provided in this documentation, we use the URL youraccountname.api-us1.com as a stand-in for your real account API URL. Your API URL can be found in your account on the My Settings page under the "Developer" tab. In addition, URL paths should begin with /api/3 to specify version 3 of the API. Generally, the URL will be in the form https://<your-account>.api-us1.com/api/3/<resource>. All API calls should be made over HTTPS.

Authentication

 

All requests to the API are authenticated by providing your API key. The API key should be provided as an HTTP header named Api-Token.

Header
curl -H "Api-Token: YOUR_TOKEN" https://account.api-us1.com/api/3/
 
Your API key can be found in your account on the Settings page under the "Developer" tab. Each user in your ActiveCampaign account has their own unique API key.
 
❗️Remember to keep your API key secret. Do not share it and take care not to expose it publicly in client-side code.
 

HTTP Methods

 

The v3 API uses standard HTTP methods for indicating the action to take on a resource.

Method Action
GET Retrieve a resource.
POST Create a new resource.
PUT Update a resource (including partial updates).
DELETE Remove a resource.

 

Schema

 

All API requests and response bodies adhere to a common JSON format representing individual items, collections of items, links to related items and additional meta data.

 

Single Resources

Individual resources are represented by top level member named after the resource in the singular form. Below is a representation of a single contact. This could be used in the body of a PUT request and it’s what would be returned in the body of a GET request.

{
    "contact": {
        "email": "jsmith@example.com",
        "firstName": "John",
        "lastName": "Smith"
    }
}
 
 

Collections

Collections of resources are represented by a top level member named after the resource in the plural form. Below is a representation of a collection of contacts.

{
    "contacts": [
        {
            "email": "jsmith@example.com",
            "firstName": "John",
            "lastName": "Smith"
        },
        {
            "email": "alice@example.com",
            "firstName": "Alice",
            "lastName": "Jones"
        }
    ],
    "meta": {
        "total": "2"
    }
}
 
 

Relationships

A resource may define relationships to other resources. The name of a relationship generally reflects the type of the related resource. The name will be singular if there is only one related resource or plural if there are many related resources.

Links

Resources may provide links to related resources by defining a member named “links” within the resource’s object representation. Links are defined as an object where the key name represents the name of the relationship and the value is a URL to the related resource(s). For example, here is a representation of a contact with links to the contact’s contact lists and the contact’s organization.

{
   "contact": {
       "id": 1,
       "email": "jsmith@example.com",
       "firstName": "John",
       "lastName": "Smith"
       "links": {
           "contactLists": "https://:account.api-us1.com/api/3/contacts/1/contactLists",
           "organization": "https://:account.api-us1.com/api/3/contacts/1/organization"
       }
   }
}
 
 

Sideloading

Related resources can be included in a response by setting the include query parameter to a comma delimited list of relationships. Nested relationships may also be included by using a period to chain together relationships. The resulting JSON will include collections for each type of resource and resources will have properties identifying their related resources. This is referred to as “sideloading”. Below is an example of request for contacts including related contact lists, lists and organization.

GET api/3/contacts?include=contactLists.list,organization

{
   "contacts": [
       {
           "id": 1,
           "email": "jsmith@example.com",
           "firstName": "John",
           "lastName": "Smith",
           "contactLists": [3,5],
           "organization": 7,
       }
   ],
   "contactLists": [
       {
           "id": 3,
           "list": 5
       },
       {
           "id": 6,
           "list": 10
       }
   ],
   "lists": [
       {
           "id": 5,
           "name": "Monthly Newsletter"
       },
       {
           "id": 10,
           "name": "Daily Deals"
       }
   ],
   "organization": [
       {
           "id": 7,
           "name": "ActiveCampaign"
       }
   ]
}
 

Meta

Meta data can be represented as a top level member named “meta”. Any information may be provided in the meta data. It’s most common use is to return the total number of records when requesting a collection of resources.

GET api/3/contacts?limit=2

{
   "contacts": [
       {
           "id": 1,
           "email": "jsmith@example.com",
           "firstName": "John",
           "lastName": "Smith"
       },
       {
           "id": 2,
           "email": "alice@example.com",
           "firstName": "Alice",
           "lastName": "Jones"
       }
 ],
 "meta": {
    "total": 36
  }
}
 

Pagination, Ordering, and Filtering

 

Pagination

Endpoints that return collections of resources must limit the number of records returned in a given response. The query parameter limit can be used to alter the number of records returned. A typical endpoint will return 20 records by default and will allow a maximum of 100 records to be returned. The query parameter offset can be used to offset the result set. These query parameters can be combined to recover all records in a collection through a series of requests by incrementing the offset by the value of limit with each request.

Parameter Description
limit The number of results to display in each page (default = 20; max = 100).
offset The starting point for the result set of a page. This is a zero-based index. For example, if there are 39 total records and the limit is the default of 20, use offset=20 to get the second page of results.

The total number of results in a collection can be found in the meta.total property of the response.

 

Ordering

The orders parameter is available to apply multiple sorting criteria to a request. The parameter is set as an array where the key is the field to be sorted by and the value is the direction of sort, either ASC or DESC. Not all fields are available for ordering. The order in which sorting criteria is applied reflects the order in which the parameters are set in the query string. In the example below the results are first sorted by the contacts last name, and then sorted by the contacts email address.

GET api/3/contacts?orders[lastName]=ASC&orders[email]=DESC

{
   "contacts": [
       {
           "email": "janderson@example.com",
           "firstName": "John",
           "lastName": "Anderson"
       },
       {
           "email": "banderson@example.com",
           "firstName": "Brian",
           "lastName": "Anderson"
       },
       {
           "email": "alice@example.com",
           "firstName": "Alice",
           "lastName": "Jones"
       }
 ]
}
 

Filtering

The filters query parameter is available to apply multiple, convention oriented filters to a request. The parameter is set as an array where the key is the field to be filtered by and the value is the value to filter by. Not all fields are available for filtering in this way. Field filters will match on “equals” or “contains” on a case by case basis, as configured in the API endpoint. In the example below the results are filtered to goals in automation 5 with a name that contains “ecom”.

GET api/3/goals?filters[seriesid]=5&filters[name]=ecom

{
   "goals": [
       {
           "name": "Recommended to Friend",
           "automation": "5"
       },
       {
           "name": "Power Ecom User",
           "automation": "5"
       }
   ]
}
 

Errors

 

The API uses HTTP status codes to indicate an error has occurred while processing a request. There are four main error status codes used by the API:

Code Description
403 The request could not be authenticated or the authenticated user is not authorized to access the requested resource.
404 The requested resource does not exist.
422 The request could not be processed, usually due to a missing or invalid parameter.
429 The user has sent too many requests in a given amount of time ("rate limiting") - contact support or account manager for more details.

In the case of 422 errors the response will also include an error object with an explanation of fields that are missing or invalid. Here is an example:

HTTP/1.1 422 Unprocessable Entity

{
  "errors": [
    {
      "title": "The connection service was not provided."
    },
    {
      "title": "The connection externalid was not provided."
    }
  ]
}

In the case of 401 errors the response includes an error object such as:

{"message":"No Result found for CustomerAccount with id 2"}
 

Rate Limits

 

Our API has a rate limit of 5 requests per second per account.

 

Guidance

 

To ensure the best experience with using APIs, please observe the following guidelines.

  • Use version 3 (v3) APIs whenever possible instead of v1.
  • If an error occurs, please pause or "sleep" execution for at least 1,000 milliseconds before resubmitting your API request.

We are actively working on improving our platform experience, adding new features, and improving performance. Following these guidelines will reduce intermittent errors and help us to provide a better experience for all customers.

Related articles

Powered by Zendesk