Custom Activities Quick Start

[Tyron_Pretorius]

As a Marketo user I am sure you are aware of the standard activities that Marketo tracks such as email opens, webpage visits, and form fills. But what about the wealth of activities that are unique to your business? How can you get these into Marketo? Custom activities that’s how!

Custom activities are a powerful way to get your business’s unique customer behavior into Marketo so that you can get deeper insights into your customer’s behavior and use these custom behaviors as smart list filters and triggers to enhance your automation and personalized outreach.

The documentation on custom activities is sparse, to say the least, but don’t you worry in this blog post I will explain what a custom activity is, how we can set one up, how we can test it works, and how we can send custom activities from our code.

What is a Custom Activity?

A custom activity is an activity that you define upon creation with a primary field and supplementary fields which then become the constraints of this activity in smart list filters and triggers. Custom activities also appear in the activity log so that you can see these activities alongside all the standard activities which are tracked in Marketo.

If you use the Segment CDP and you want to map your Segment events to custom activities then check out the “Mapping a Custom Activity to a Segment Event” section in this blog post.

Custom Activity Primary Field

The custom activity primary field, designated by the asterisk in the image below, is a field that must always be present when the activity is being sent to Marketo and it must be of the string data type. As explained by Justin Norris, the primary field for a Marketo activity usually refers to the object that the activity refers to:

• For “Visits Web Page” the primary field would be “web page”
• For “Fills out Form” the primary field would be “form”
• For “Opens Email” the primary field would be “email”

Custom Activity Fields

Custom Activity Trigger and Filter Showing Available Constraints

So for example in the images above a more applicable primary field could have been “number” for the “Number Search” custom activity, provided that this activity always has a “number” property present when it is being sent to Marketo.

As you see in the images though, the “timestamp” field is used as the primary field and you can see how it is displayed as the primary constraint on the trigger and filter for the custom activity. When you are merely trying to trigger or filter for the custom activity the value of this primary constraint does not matter, hence why the “is not empty” condition is used in the images above.

Consequently, the choice of primary field does not matter so long as it is always present when the activity is being sent to Marketo and it is of the string data type.

Other Custom Activity Fields

You only need to have the primary field set for the custom activity to function correctly. However, if you want to have additional constraints available on the custom activity filters and triggers then you will need to create more fields on the custom activity (see images above).

If you want to find out how you can transfer values from these custom activity fields into person fields then check out the Trigger Tokens with Custom Activities section.

Creating a Custom Activity

Custom Activity Details

1. Navigate to “Admin” > “Custom Activities”
2. Click on “New Custom Activity”
3. Fill out the “Display Name” and modify the “API Name” if you wish
4. Click “Next”
5. Fill out the “Filter” and “Trigger” names
6. Click “Next”
7. Fill out the “Name” and “API Name” of the primary field
8. Click “Submit”

For any additional activity fields that you want to use as constraints on the filter and trigger:

1. Navigate to the “Fields” tab
2. Click “New Field”
3. Select the field “Data Type”
4. Enter a “Name”
5. Rename the “API Name” field if you wish
6. Hit “Save”

Finally, to approve the custom activity and get the “Custom Activity ID”:

1. Click the “Custom Activity Actions” dropdown
2. Select “Approve Activity”
3. Copy the Custom Activity ID that appears once the activity is approved

You will need this custom activity ID when mapping the activity to an event from another platform like Segment and when making API requests to send this activity to Marketo using Postman and code (see the section below).

Sending a Custom Activity to Marketo

Once you have created the custom activity and copied the activity ID you are then ready to test that it works. To do this we are going to use the free API testing tool called Postman. If it is your first time using Postman and the Marketo API I highly recommend checking out the API Quick Start Guide, which will show you how to make your first API requests in Postman.

In the quick start guide, there is also a form that will allow you to download the Marketo API Postman collection which includes the request we are going to use below to send a custom activity to Marketo.

Sending a Custom Activity Using Postman

Postman request to send custom activity to Marketo

To build this API request we are going to make a POST request to the endpoint below.

{{base_url}}/rest/v1/activities/external.json

Then we will specify the custom activity ID, the primary field value, and the values for any other fields present in our custom activity. We also have to specify the timestamp for when the activity occurred (this will be the time it is displayed in the activity log) along with the lead ID for the person who carried out this activity.

{
	"input": [{
		"activityDate": "{{Timestamp}}",
		"activityTypeId": {{Activity ID}},
		"attributes": [
                      {
			"apiName": "{{Field 1 API Name}}",
			"value": {{Field 1 Value}}
		       } ,
                       {
			"apiName": "{{Field 2 API Name}}",
			"value": {{Field 2 Value}}
		       },
                      {
			"apiName": "{{Field 3 API Name}}",
			"value": {{Field 3 Value}}
		       }
                 ],
		"leadId": {{Lead ID}},
		"primaryAttributeValue": "{{Primary Field Value}}"
	}]
}

Once we send this custom activity to Marketo we can then check the activity log for the lead whose lead ID we specified in the API request. Make sure to check the activity log around the same time as the activityDate we specified in the API request above.

N.B. The API works on UTC time so when you specify the activityDate value that the time will appear differently in the activity log of your Marketo instance (presuming your instance is not on UTC time).

Sending Custom Activities from Your Code

Getting the code for sending a custom activity to Marketo

Once you have configured the request in Postman to send the custom activity to Marketo, Postman makes it super simple to export this request in any programming language of your choosing.

1. Click on the code icon on the right-hand-side
2. Select your preferred programming language from the dropdown
3. Copy and paste the generated snippet into your code

It’s that easy!

Don’t you just love Postman 

What’s After Custom Activities?

Now that you know how to set up custom activities in Marketo and have gotten exposure to the API why don’t you check out the posts below to further your knowledge of the API and what it can do for you:

• Bulk API Quick-Start Guide
• UTM Tracking & Automation
• Merge Leads in Bulk using the API