Activities

Last update: November 4, 2024

CREATED FOR:

  • Admin

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 has its own unique id, leadId and activityDate, the primaryAttributeValueId and primaryAttributeValue values 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.

Most activities will be purged after some period of time.

Describe

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

GET /rest/v1/activities/types.json

  "requestId": "6e78#148ad3b76f1",
  "success": true,
  "result": [
    {
      "id": 2,
      "name": "Fill Out Form",
      "description": "User fills out and submits form on web page",
      "primaryAttribute": {
        "name": "Webform ID",
        "dataType": "integer"
      },
      "attributes": [
        {
          "name": "Client IP Address",
          "dataType": "string"
        },
        {
          "name": "Form Fields",
          "dataType": "text"
        },
        {
          "name": "Query Parameters",
          "dataType": "string"
        },
        {
          "name": "Referrer URL",
          "dataType": "string"
        },
        {
          "name": "User Agent",
          "dataType": "string"
        },
        {
          "name": "Webpage ID",
          "dataType": "integer"
        }
      ]
    }
  ]
}

Real world responses 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 that 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 data types. Note that if the field is empty, then that particular attribute is omitted from an individual activity record.

Query

To retrieve activities from Marketo, call the Get Lead Activities endpoint. You 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 a comma separated list.

GET /rest/v1/activities.json?activityTypeIds=1&nextPageToken=WQV2VQVPPCKHC6AQYVK7JDSA3I3LCWXH3Y6IIZ7YSGQLXHCPVE5Q====

{
  "requestId": "24fd#15188a88d7f",
  "result": [
    {
      "id": 102988,
      "marketoGUID": "102988",
      "leadId": 1,
      "activityDate": "2023-01-16T23:32:19Z",
      "activityTypeId": 1,
      "primaryAttributeValueId": 71,
      "primaryAttributeValue": "localhost/munchkintest2.html",
      "attributes": [
        {
          "name": "Client IP Address",
          "value": "10.0.19.252"
        },
        {
          "name": "Query Parameters",
          "value": ""
        },
        {
          "name": "Referrer URL",
          "value": ""
        },
        {
          "name": "User Agent",
          "value": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.95 Safari/537.36"
        },
        {
          "name": "Webpage URL",
          "value": "/munchkintest2.html"
        }
      ]
    }
  ],
  "success": true,
  "nextPageToken": "WQV2VQVPPCKHC6AQYVK7JDSA3J62DUSJ3EXJGDPTKPEBFW3SAVUA====",
  "moreResult": false
}

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 always returns 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 that 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.