Activities

Activities Endpoint Reference

Marketo permits a huge variety of activity types related to lead records.  Nearly every change, action or flow step is recorded against a lead’s activity log and can be retrieved via the API or leveraged in Smart List and Smart Campaign filters and triggers.  Activities are always related back to the lead record via the leadId, corresponding to the Id field of the record, and also has a unique id of its own.

There are a very large number of potential activity types, which may vary from subscription to subscription, and have unique definitions for each.  While every activity will have its own unique id,  leadId and activityDate, the primaryAttributeValueId and primaryAttributeValue will vary in their meaning.

Marketo also permits the creation of Custom Activity Types through the Custom Activities Metadata API.  Adding custom activities is done through the Add Custom Activities API.

Describe

To retrieve a list of available types and their definitions for an instance, you can use the Get Activity Types endpoint.

Real world responses will include far more definitions.  In this example, the type shown is a “Fill Out Form”, which has a primary attribute of “Webform ID”, which refers back to the Marketo ID of the form which was filled out, and can be used to relate back to that particular asset in Marketo.  Additionally, there are definitions for each of the possible attributes of a particular activity record of this type and their datatypes.  Note that if the field is empty, then that particular attribute will be omitted from an individual activity record.

Query

To retrieve activities from Marketo, call the Get Lead Activities endpoint.  You’ll need to first retrieve a paging token for the datetime that you want to begin retrieving activities from.  You then pass the paging token in the nextPageToken query parameter.  In addition, you pass up to ten activity type Ids in the activityTypeIds query parameter as a comma-separated list.

You can optionally include either a listId query parameter to narrow your search to only those records included in a specific static list, or a leadIds query parameter and search for activities from only a specified set of leads.  You can pass up to 30 leadIds as comma separated list.

For the first call, use the Get Paging Token API to get nextPageToken. For subsequent calls to this endpoint, use the nextPageToken returned from the response. This endpoint will always return the nextPageToken.

If the moreResult attribute is true, this means more results are available. Continue to call this endpoint until the moreResult attribute returns false, which means there are no results available. The nextPageToken returned from this API should always be reused for the next iteration of this call.

In some cases, this API may respond with fewer than 300 activity items, but also have the moreResult attribute set to true.  This indicates there are more activities that can be returned and that the endpoint can be queried for more recent activities by including the returned nextPageToken in a subsequent call.

Note that within each result array item, the id integer attribute is being replaced by the “marketoGUID” string attribute as unique identifier.  For additional information, please see this post.

Data Value Changes

For Data Value Change activities, a specialized version of the activities API is provided.  The Get Lead  Changes endpoint will only return activities of Data Value Change records to lead fields.  The interface is the same as the Get Lead Activities API with two differences:

  • There is no activityTypeIds parameter, since the endpoint only returns Data Value Change activities.
  • The fields query parameter is required, where you can pass a comma-separated list of fields to indicate which fields you want to retrieve changes for.

Each activity in the response will have a fields array, including a list of changes in the activity, which will specify the id and name of the field changed, as well as the new and old values relative to the change.

Note that within each result array item, the id integer attribute is being replaced by the “marketoGUID” string attribute as unique identifier.  For additional information, please see this post.

Deleted Leads

There is also a special endpoint Get Deleted Leads for retrieving deleted activities from Marketo.

Note that within each result array item, the id integer attribute is being replaced by the “marketoGUID” string attribute as unique identifier.  For additional information, please see this post.

Page Though Results

By default, the endpoints mentioned in this section will return 300 activity items at a time.  If the moreResult attribute is true, this means that more results are available. Continue to call the endpoint until the moreResult attribute returns false, which means that there are no more results available. The nextPageToken returned from this endpoint should always be reused for the next iteration of this call.

In some cases, this endpoint may respond with fewer than 300 activity items, but also have the moreResult attribute set to true.  This indicates there are additional  activities that can be returned and that the endpoint can be queried for more recent activities by including the returned nextPageToken in a subsequent call.  Note that the nextPageToken needs to be URL Encoded in the request.

Custom Activity Types

Custom Activities function just like standard activities, except the schema is managed by third-parties, and not by Marketo.  Instances of custom activities are linked to lead records through the leadId just as standard activities, but both primary and secondary attributes are arbitrarily defined.  When a custom activity type is approved, a corresponding Smart List trigger and filter are created, so that leads can be processed based on current or historical custom activity data.

Retrieving custom activity data is done in the same way as standard activities, through the Get Lead Activities API.

Query Types

In addition to the standard Get Activity Types endpoint, the Get Custom Activity Types and Describe Custom Activity Type endpoints will return details about the activity types provisioned in the Marketo instance, and metadata regarding the attributes for a given type.  The normal Get Activity Types will still return metadata regarding custom activities, but will not indicate whether a given type is custom.

Get Types

Describe Type

For type descriptions you must pass apiName as a path parameter.  By default you will get the approved version of the activity.  You can optionally pass the draft=true parameter in order to retrieve the draft version of the activity.

Create Type

Each custom activity type requires a display name, API name, trigger name, filter name, and primary attribute.

To ensure consistency of your types with Marketo conventions, and to avoid collisions, it is important to follow a few guidelines when creating your types:

Display Name: The display name of the activity type should briefly describe what an activity record represents, such as “Send Email”, or “Change Data Value”.  These names should typically be in the infinitive form, i.e. “Attend Event”.  Display names accept alphanumeric characters, spaces and underscores.  Display names must contain at least one letter.

API Name: The API name is comprised of alphanumeric characters (maximum length of 255).  If you are a LaunchPoint partner, you should prepend a representative namespace to your activity type API names.  This is to avoid collisions with customer-provisioned types.  Convention is to use all lowercase or camelCase to help distinguish between other text strings.

Description: For activities which may have non-obvious behavior should include a description of what the activity type represents with relation to the lead.

Trigger Name: Each activity type must have a unique, human-readable trigger name.  Trigger names should be in the third-person present tense, such as “Attends an Event”.  LaunchPoint partners should include their company name in the activity, such as “Attends Webinar – Acme Company.”

Filter Name:  Each activity type must have a unique, human-readable filter name.  Filter names should be in the third-person past tense, such as “Attended an Event”.  LaunchPoint partners should include their company name in the activity, i.e. “Attended Webinar – Acme Company.”

Primary Attribute: The primary attribute of a custom activity should be the most significant field for the activity type.  For example, for an “Attended Event” activity this would be the name of the event.  Primary attributes are included as parameters by default in every instance of a trigger or filter for that activity type, and the value will be displayed in the activity log of a person record without requiring drill-down into the activity.

When a custom activity is created, it is created as a draft, and must be approved before it can be used to add activity records of that type.  All updates are implicitly applied to the draft version of the type.  To reflect the changes in the live version of the type, it must be approved.  When a custom activity type is approved and in use, no changes to the above fields may be made.

When creating a type, the description parameter is optional, while all of the following parameters are required: apiName, name, triggerName, filterName, primaryAttribute.

Update Type

Updating a type is very similar, except the apiName is the only required parameter as a path parameter.

Approve Type

Types can be managed with the Approve Custom Activity Type, Discard Custom Activity Type Draft, and Delete Custom Activity Type, just like standard Marketo assets.

Custom Activity Type Attributes

Each custom activity type can have from 0-20 secondary attributes.  Secondary attributes may have any valid field type for a Marketo field.  They are added, updated, and removed separately from the parent type, but may be edited while an activity type is in use and then approved.  When fields are edited on a live type, then all activities of that type created after approval will have the new secondary attribute set.  Changes will not be applied retroactively to existing activities sharing that type.

Be careful about the removal of attributes, as this will affect their availability for use in the corresponding filters.

 

Updates made to the secondary attribute list use the API name of each attribute as a primary key.  The API Name for an attribute may not be changed, it must be deleted and added again with the desired API name.

Valid data types for attributes are: string, boolean, integer, float, link, email, currency, date, datetime, phone, text.

When changing the primary attribute of an activity type, any existing primary attribute should be demoted by setting isPrimary to false first.

Create Attributes

Creating an attribute takes a required apiName path parameter.  Also required are name and dataType parameters.  The description and isPrimary parameters are optional.

Update Attributes

When performing updates to attributes, the apiName of the attribute is the primary key.  The apiName parameter must exist for the update to succeed (i.e. you cannot change the apiName parameter using update).

Delete Attributes

Deleting an attribute takes a required apiName path parameter that is the custom activity API name.   Also required is an attributes parameter that is an array of attribute objects.  Each object must contain an apiName parameter that is the custom activity type API name.

Add Custom Activities

Custom activities are write-once records of historical activities related to individual person records in Marketo.  These activities have a schema which is managed by Marketo Admins or remotely via an API integration.  Custom activities are added to lead records via the Add Custom Activities endpoint and related to each lead record via its leadId field.  Custom activities can be viewed in the user interface via the lead’s activity log, or retrived via Get Lead Activities endpoint by specifying the custom activity’s type ID.

Custom activities are appropriate for recording data which is related to a single person record and which does not need to be updated or overwritten.  An example would be recording a person attending an event as an “Attended Event” activity.  For records related to a person that may change, such as student enrollment, custom objects should be used instead, as they can be updated, where custom activities may not.

The input member is an array of activity objects.  A maximum of 300 activity records can be submitted at a time.

The leadId, activityDate, activityTypeId, primaryAttributeValue, and attributes members are required. The attributes array must contain the non-primary attribute.  This can be specified using either name (field name), or apiName (API name), and value which corresponds to the value that you are setting.

Note that within each result array item, the id integer attribute is being replaced by the “marketoGUID” string attribute as unique identifier.  For additional information, please see this post.