Contact Event Tracking API Guide

How to use the ActiveCampaign API to store events, and trigger automations

This tutorial will show you how to send event logs for your Contacts, using the ActiveCampaign v3 API. For a complete overview of Event Tracking, please see this guide.

💥 Events Explained

Any user activity your API registers can be considered an event. Because the ways users interact with APIs varies as widely as the APIs themselves, ActiveCampaign has built Event Tracking to be extremely flexible, being able to track all different types of events.

Examples of user events:

  • Login/Logout
  • Button clicks
  • Credential updates
  • Purchases
  • Downloads

Why capture Events?

You can create an event for any activity on your website or app and assign it a value. As you begin to capture event data and send it to your ActiveCampaign account, you can use it to improve your marketing and sales processes as well as use it to trigger automations, create segment conditions, and personalize campaigns.

🏗️ Preparing Events

In this tutorial, we will be creating a "file download request" event, which will notify ActiveCampaign to send a Contact an email that contains a with a link to a file.

Turn on Event Tracking

In the UI

To turn on Event Tracking on your account, go to
Go to "WEBSITE" -> "Site Tracking" -> "Event Tracking" -> scroll down and turn tracking status toggle to "ON."

Make note of the Event Key, this is key necessary to send events to your ActiveCampaign account, and will need to be included in every request. In this demo, the key is baf2815c4c1d1cc1fa4fbf2b715005282bb3b2e7 yours will be different.

3261

"WEBSITE" -> "SITE TRACKING" -> "EVENT TRACKING" and turn tracking status to "ON"

With the API

Pausing or resuming event tracking can be easily done through the api:

Turn Event Tracking On/Off:

Send a POST to https://{{yourAccountName}}.api-us1.com/api/3/eventTracking with the following body to turn event tracking on* or off**:

{
  "eventTracking": {
    "enabled": false
  }
}
{
  "eventTracking": {
    "enabled": false
  }
}

Get Event Tracking Status

A GET request to https://{{yourAccountName}}.api-us1.com/api/3/eventTracking will return the event tracking status:

{
    "eventTracking": {
        "enabled": true
    }
}

✔️ Whitelisting Events

You can log any event name to a Contact, but if you want to use those event names in automations, it's a good idea to "whitelist" the event names first.

In the UI

Enter in the name of the event you would like to have available when building automations, and click "Add"

2824

Enter your desired event name, and click "Add"

With The API

Create a whitelisted event name

A POST to https://{{yourAccountName}}.api-us1.com/api/3/eventTrackingEvents will create the whitelisted event name:

{
    "eventTrackingEvent": {
        "name": "file download request"
    }
}

Retrieve a list of event names

A GET to https://{{yourAccountName}}.api-us1.com/api/3/eventTrackingEvents will return a list of whitelisted event names:

{
    "eventTrackingEvents": [
        {
            "name": "file download request"
        }
    ],
    "meta": {
        "total": 1
    }
}

Tracking Events

So far we have turned on event tracking, and whitelisted event names. Now we'll begin tracking events. To track events you'll need the following information:

  • Your eventKey
  • Your 9-digit actid

Both are available at yourAccountName.activehosted.com/app/settings/tracking.

Your actid can be found in the same location as your event key. Click on "Event Tracking API" and a modal will appear with your actid:

3152

Click "Event Tracking API"

1398

Your actid can be found in the modal that appears.

In this tutorial, we will be tracking an event we're calling a file download request, for our user, [email protected].

To track this event, send a POST to https://trackcmp.net/event with the following form data:

KEYVALUE
actidXXXXXXXXX
keyyourKeyWillGoHere_298398c9ac823
eventfile download request
eventdatahttps://www.yoursite.com/downloads/file.pdf
visit{"email":"[email protected]"}

You can try this out for yourself using ActiveCampaign's Postman collection

📘

What is trackcmp.net?

trackcmp.net is the ActiveCampaigned-owned endpoint for events. All event creation calls should be sent to https://trackcmp.net/event

On success, you will receive a 200 OK response:

{
    "success": 1,
    "message": "Event spawned"
}

Form Data was specifically chosen to make it easier to integrate into front-end environments, often where only a user's email address is known.

🚧

Events must be connected to existing Contact records

Every event must include a previously created Contact record. If your system sends an event for a Contact that does not exist in your account, the event log will not be written.

Your event will now be visible on the Contact record:

3214

Your event can be seen on the Contact record

🗑️ Managing Events

Now that we're writing Events to Contacts, let's look into how to delete, and view Event records.

Deleting Events

Delete any Event name by making a DELETE api call to https://{{yourAccountName}}.api-us1.com/api/3/eventTrackingEvents/{{EventName}}
(Documentation)

🚧

Deleting the Event name does not delete individual events that have already been logged.

This will only remove the event name. Any contacts that have a value associated with this event name already will still retain that association. Make sure that event tracking is enabled before making this call.

📘

Event names must be url encoded

Event names that have space(s) in them must be url encoded.

For example, to delete an Event named my event, the DELETE url call should be to https://{{yourAccountName}}.api-us1.com/api/3/eventTrackingEvents/my%20event.

Get Contact Events and Activities

If you would like to get the Events and Activities for a Contact, make a GET call ,using the Contact's id, to https://{{yourAccountName}}.api-us1.com/api/3/activities?contact={{contactId}}

For this example, the Contact we logged the event to earlier has the id of 157. The call would be a GET to https://{{yourAccountName}}.api-us1.com/api/3/activities?contact=157, which returns a 200 ok response similar to this:

{
    "trackingLogs": [
        {
            "subscriberid": "157",
            "type": "file download request",
            "value": "https://www.yoursite.com/downloads/file.pdf",
            "tstamp": "2023-03-01T15:36:03-06:00",
            "hash": "1b93f93c256d087df3778b97577232a1772b4d7f",
            "links": {
                "contact": "https://{{yourAccountName}}.api-us1.com/api/3/trackingLogs/27/contact"
            },
            "id": "27",
            "contact": "157"
        }
    ],
    "activities": [
        {
            "tstamp": "2023-03-01T15:36:03-06:00",
            "subscriberid": "157",
            "reference_type": "TrackingLog",
            "reference_id": "27",
            "reference_action": "file download request",
            "jsonData": null,
            "userid": "0",
            "permission": "",
            "referenceModelName": "tracking-log",
            "reference": {
                "type": "tracking-log",
                "id": "27"
            },
            "links": {
                "user": "https://{{yourAccountName}}.api-us1.com/api/3/activities/483/user",
                "recipients": "https://{{yourAccountName}}.api-us1.com/api/3/activities/483/recipients",
                "reference": "https://{{yourAccountName}}.api-us1.com/api/3/activities/483/reference",
                "notes": "https://{{yourAccountName}}.api-us1.com/api/3/activities/483/notes"
            },
            "id": "483",
            "user": null
        }
    ],
    "meta": {
        "total": "1"
    }
}

Get just a Contact's Events:

If you would like to get just the Events for a Contact, make a GET call ,using the Contact's id, to https://{{yourAccountName}}.api-us1.com/api/3/contacts/{{contactId}}/trackingLogs

For this example, the Contact we logged the event to earlier has the id of 157. The call would be a GET to https://{{yourAccountName}}.api-us1.com/api/3/contacts/157/trackingLogs, which returns a 200 ok response similar to this:

{
    "trackingLogs": [
        {
            "subscriberid": "157",
            "type": "file download request",
            "value": "https://www.yoursite.com/downloads/file.pdf",
            "tstamp": "2023-03-01T15:36:03-06:00",
            "hash": "1b93f93c256d087df3778b97577232a1772b4d7f",
            "links": {
                "contact": "https://{{yourAccountName}}.api-us1.com/api/3/trackingLogs/27/contact"
            },
            "id": "27",
            "contact": "157"
        }
    ]
}

🎉 Using Events

Now that you're sending and managing events successfully, you can use those events and the data they contain in powerful ways!

Events In Your Automations

You can find your Automations at yourAccountName.activehosted.com/app/automations

  • Click "Create an automation" on the top-right.
  • Select "Start From Scratch"
  • Click "Continue"
976
  • Select "Start From Scratch"
  • Click "Continue"
1214

Select "Event is recorded"

924

Select the Event Name we created earlier (make sure it is whitelisted!)

Your event will now trigger this automation!

Event Data In Your Campaigns

We're going to use the automation we created in the last step, to send an email with whatever data we'd like (in this tutorial, a link to a file).

There are many possibilities to what you can send with events, including:

  • Credential confirmation links
  • Password resets
  • File download links
646

Add a step to the automation

692

Optionally name your email, and select "Start with a template"

806

Select your preference in how you would like to design this email.

1373

Inside the email designer, select "Personalization Tags"

952

Select "Contacts" on the left menu, and scroll down till you locate your event, titled:

"Event - {{your event title}}"

828

With your Event personalization in place, you're now ready to send emails!

Now when a file download request event arrives for a Contact, any eventdata you include in the POST call to track event, will be included in the email, replacing where the *%EVENT: file download request% was:

Hello!

Here is your file link:

https://www.yoursite.com/downloads/file.pdf

498