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.

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 also 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 that set of leads.  You can pass up to 30 “leadIds” as comma separated list.

Note that within each “result” array item, the “id” integer attribute is being replaced by the “marketoGUID” string attribute as unique identifier.  This change will occur in Spring 2017 release.  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.
  • A “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.  This change will occur in Spring 2017 release.  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.  This change will occur in Spring 2017 release.  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.

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 view in the user interface via the lead’s activity log, or retrived via Get Lead Activities by 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.

Note that within each “result” array item, the “id” integer attribute is being replaced by the “marketoGUID” string attribute as unique identifier.  This change will occur in Spring 2017 release.  For additional information, please see this post.