Custom Preference Center

This guide is intended to help narrow down the ActiveCampaign API methods to use for common use-cases. In most cases, Tessitura organizations are leveraging the API to retrieve existing contact list opt-in preferences and tags and update/create contacts’ similar data in their Prospect2 accounts.

ActiveCampaign API Overview.

Authentication is highlighted at the top of the documentation and provides an example of how to pass the API Key with the request header info. Another useful section of the documentation is the pagination and filtering section, which provides a handy way to apply filters to get only the useful results.

Getting Lists (GET method)

Get a list of all available lists in the account. From the response, the id and the name are the primary data points to use. The ID will be necessary for altering a contact’s status for a particular list.

   "lists": [
       {
           "stringid": "main-pro2-list",
           "userid": "6",
           "name": "Main Pro2 List", 
           "cdate": "2017-07-21T09:02:53-05:00",
 		~
		~	
		~
           "id": "3",
           "user": "6"
       }

Getting Tags (GET method)

Get a list of all existing tags in the account. From the response, the id and tag (tag name) will be the most useful.

"tags": [
       {
           "tagType": "contact",
           "tag": "[Monthly Enews]",
           "description": "",
           "cdate": "2017-10-20T14:42:12-05:00",
           "subscriber_count": "100001",
           "created_timestamp": "2019-08-14 15:12:50",
           "updated_timestamp": "2022-12-05 16:21:32",
           "created_by": null,
           "updated_by": null,
           "id": "44"
       }

Getting Existing Contact Preferences (GET method)

Get existing contact record. In order to retrieve a contact record by email address, the email should be passed with a email URL argument. Then, to also include current list preferences and tags, the data needs to be sideloaded (more about sideloading here) by specifying the include argument with the data points contactLists & contactTags.

Example:

https://youraccountname.api-us1.com/api/3/contacts?email=contact@example.com&include=contactLists,contactTags

The response will contain several data points, but the two most important ones are the list and status data points. The list value is the id that matches the list id from the lists endpoint outlined above. The status value is the contact’s current status on that list (1 = subscribed, 2 = unsubscribed). If the list is not present in the response, that contact does not have an affiliation with that list.

Lists

   "contactLists": [
       {
           "contact": "298110",
           "list": "3",
           "form": null,
           "seriesid": "0",
           "sdate": "2022-08-03T12:47:41-05:00",
           "udate": null,
           "status": "1",
           "unsubreason": "",
           "first_name": "Stephen",
           "last_name": "Lynch",
           "unsubscribeAutomation": null,
           "id": "374460",
           "automation": null
       }

Updating a List Preference (POST method)

Update list status for contact. This method allows you to manage the status of a list for a given contact id. In the below example, the request will subscribe the contact (298110) to list 107–in the previous example, contact 298110 was unsubscribed (status 2) from list 107.

{
    "contactList": {
        "list": 107,
        "contact": 298110,
        "status": 1
    }
}

This method should only be employed when there is a specific permission by the contact to change the status from unsubscribed to subscribed. (eg. a Manage Preferences page where the contact selected the list to be subscribed to).

Adding a Tag to a Contact (POST method)

Adding a Tag to a Contact. The contact value is the contact id and the tag value is the id of the tag itself from the earlier tag list method.

{
    "contactTag": {
        "contact": "298110",
        "tag": "20"
    }
}

Removing a Tag from a Contact (DELETE method)

Removing a tag from a Contact. To remove a tag from a contact, pass a DELETE action to the /contactTags endpoint with the id of the contact-tag association. This is not the tag id, nor the contact id, but the ID of the record that represents the tag associated with the contact.

   "contactTags": [
       {
           "contact": "298110",
           "tag": "61", ([FirstTimerBuyer] tag)
           "cdate": "2022-04-18T11:42:07-05:00",
           "created_timestamp": "2022-04-18 11:42:07",
           "updated_timestamp": "2022-04-18 11:42:07",
           "created_by": null,
           "updated_by": null,
           "links": {
           },
           "id": "2630423" ← ID of the tag association
       }

To remove the [FirstTimeBuyer] tag from contact 298110, use the DELETE action with the following request URL:

https://youraccountname.api-us1.com/api/3/contactTags/2630423

Getting Automations (GET method)

Retrieve all automations from your account. The id and status values are the most widely used data points.

"automations": [
       {
           "name": "Re-engagement campaign",
           "cdate": "2017-10-24T13:19:14-05:00",
           "mdate": "2017-10-24T13:19:14-05:00",
           "userid": "1",
           "status": "2",
           "entered": "0",
           "exited": "0",
           "hidden": "0",
           "entitlements_violation": null,
           "defaultscreenshot": "//img-us1.com/default-series.gif",
           "id": "11"
       }

Adding a Contact to an Automation (POST method)

Add a contact to an automation. To add a contact to an automation, the contact ID and the automation ID are all that’s required. You can retrieve the automation ID from the request method above.

{
    "contactAutomation": {
        "contact": "298110",
        "automation": "42"
    }
}

Changing an Existing Contact’s Email Address

Updating the email address of an existing contact record via the API is a 2-step process. The first step is to identify the contact record for the contact with the email address you’re looking to change. Once you’ve identified the contact record, you’ll use the contact id to update the email address for that contact.

Identify the Existing Contact Record

The method for retrieving an existing contact record by email is similar to the earlier method used to get an existing contact’s list and tag settings, minus the data sideloading. In order to retrieve a contact record by email address, the email should be passed with a email URL argument as shown below:

Example:

https://youraccountname.api-us1.com/api/3/contacts?email=contact@example.com

The response will contain several data points, but the most important one is the id data point within the contacts data array.

   "contacts": [
       {
           "cdate": "2022-02-11T14:30:22-06:00",
           "email": "email@example.com",
           "phone": "1112223333",
           "firstName": "Stephen",
           "lastName": "Lynch",
           ~
           ~
           ~
          "id": "298110",
           "organization": null
       }
   ]

Updating an Existing Contact

Update a Contact Record. Now that the contact id has been identified, that will be used in the next API call to update that contact record.

Request URL Example:

https://youraccountname.api-us1.com/api/3/contacts/298110

Request Body Example:

{
    "contact": {
        "email": "stephen@example.com",
        "firstName": "Stephen",
        "lastName": "Lynch",
        "fieldValues": [{
                "field": "1",
                "value": "The Value for First Field"
            },
            {
                "field": "6",
                "value": "2008-01-20"
            }
        ]
    }
}

In the above example, multiple fields were included in the request body. If the email address is the only data point that is changing, all other fields and arrays can be omitted–existing values on other fields will not be overwritten unless they are included in the request body with empty or alternate values.