Visitor Activity Object

Use activities resources to learn how visitors and prospects have interacted with your website. Examples of activities include:

  • viewing and clicking your website
  • submitting a form
  • clicking a social media post

For more information on the types of activities, see Visitor Activity. Learn more about visitor activities in Salesforce Help.

Include the authentication header with every request. For information on how to authenticate, see Authentication.

Resource NameOperationDescription
Visitor Activity ReadGETReturns information for a single visitor activity.
Visitor Activity QueryGETReturns information for up to 200 activities.

Returns information for the specified activity. Specify the activity by Account Engagement ID.

Return the information for the activity with Account Engagement ID 153879xxx.

Returns information about activities that match the specified criteria. You can specify which kinds of activities and which fields to return. A maximum of 200 activities are returned.

Use these parameters to specify which activities are returned. Parameters can be used in any combination and in any order unless specified otherwise.

For all requests:

  • Parameters must be URL-encoded.
  • Dates and times must use GNU Date Input Syntax, for example yyyy-mm-dd:hh:ss.

For a full listing of visitor activity fields, see Visitor Activity.

ParameterDatatypeOptionsDescription
created_afterStringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Returns activities created after the specified time. For example, to return all activities created after January 1, 2020, use /api/visitorActivity/version/4/do/query?created_after=2020-01-01 00:00:00
created_beforeStringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Returns activities created before the specified time.
id_greater_thanIntegerany positive integerReturns activities with an Account Engagement ID greater than the specified integer.
id_less_thanIntegerany positive integerReturns activities with an Account Engagement ID less than the specified integer.
updated_afterStringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Returns activities updated after the specified time.
updated_beforeStringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Returns activities updated before the specified time.
prospect_onlybooleantrue or falseReturns activities for prospects, but not for visitors. Prospects are visitors who have an associated email address in Account Engagement.
typearrayany valid type of visitor activityReturns activities of the specified types. Separate types with a comma. For more information on the types of activities, see Visitor Activity Types. Type Session is omitted. For example, to return only "click" and "view" activities, use /api/visitorActivity/version/4/do/query?type=1,2

Use these parameters to request activities that are associated with a category of visitor or prospect action. For example, you can request activities created when prospects or visitors fill out a form.

You can use only one of these parameters per request.

ParameterDatatypeDescription
custom_url_onlybooleanReturns activities created when a visitor or prospect clicks a custom redirect URL. See "Custom Redirect Reporting" in the Account Engagement Administrator guide. For example, to return only activities created when a user clicked a custom redirect URL, use /api/visitorActivity/version/4/do/query?custom_url_only=true.
email_onlybooleanReturns activities created when a prospect interacts with an email. For example, an activity is created when an email is sent to a prospect. Another activity is created when a prospect opens an email.
file_onlybooleanReturns activities created when a visitor or prospect opens, views, or downloads a file.
form_onlybooleanReturns activities created when a visitor or prospect interacts with a form on an Account Engagement landing page. Interaction includes activities like viewing, filling out, and submitting a form.
form_handler_onlybooleanReturns activities created when a visitor or prospect interacts with a form in a form handler, typically not hosted on an Account Engagement landing page. Interaction includes activities like viewing, filling out, and submitting a form.
landing_page_onlybooleanReturns activities created when a visitor or prospect interacts with an Account Engagement landing page. Interaction includes activities like viewing the page, or clicking links in the page.

Use these parameters to request activities that are related to a specific record. For example, you can request all activities that resulted from the "Spring Into Fall" campaign. We recommend using POST for this request.

You can specify multiple IDs in the same request. Separate IDs with a comma.

ParameterDatatypeOptionsDescription
campaign_idIntegerany valid campaign IDReturns activities associated with the specified campaign. For example, to return activities that were created as a result of the campaign with ID 1131xx, use /api/visitorActivity/version/4/do/query?campaign_id=1131xx
custom_url_idIntegerany valid custom URL IDReturns activities associated with the specified custom redirect.
email_idIntegerany valid email IDReturns activities associated with the specified email.
file_idIntegerany valid file IDReturns activities associated with the specified file IDs.
form_idIntegerany valid form IDReturns activities associated with the specified form IDs.
form_handler_idIntegerany valid form handlerReturns activities associated with the specified form handler IDs.
landing_page_idIntegerany valid landing page IDReturns activities associated with the specified landing page IDs.
prospect_idIntegerany valid prospect IDReturns activities associated with one of the specified prospect IDs.
visitor_idIntegerany valid visitor IDReturns activities associated with one of the specified Visitor IDs.

Use these parameters to specify which prospect or visitor fields are returned, and how the results are sorted.

ParameterDatatypeOptionsDescription
limitIntegerThe number of activities to return. The minimum value is 1 and the maximum value is 200. The default value is 200.
offsetIntegerThe number of activities to omit from the response (the number to "skip over"). For example, to retrieve a list of activities, omitting the 50 most recently updated activities, sort the query by the updated_at field and use offset=50: /api/visitorActivity/version/4/do/query?sort_by=updated_at&offset=50
outputStringThe format to use when returning the results of the query. Possible values are simple and mobile. See XML Response.
sort_byStringThe field by which the results are sorted. You can sort by created_at, id, probability, or value. See Sorting Options.
sort_orderStringThe sort order. Possible values are ascending and descending. The default value depends on which sort_by parameter you specify. See Sorting Options.

You can control how the results are sorted using the sort_by and sort_order parameters.

ValueDescription
created_atSort the results by the created_at timestamps of the activities. The default sort order is descending.
idSort the results by the IDs of the activities. The default sort order is ascending.
prospect_idSort the results by the related prospect ID of the activities. The default sort order is descending.
visitor_idSort the results by the related visitor ID of the activities. The default sort order is descending.
updated_atSort the results by the updated_at timestamps of the activities. The default sort order is descending.

To request activities associated with the prospects with Account Engagement IDs 1234xxx and 5678xxx, use this endpoint:

To request activities associated with files that resulted from a campaign with ID equal to 1234, use this endpoint:

The XML response to a visitor activity query request contains information for up to 200 activities. The XML response to a visitor activity read request contains information for the specified activity.

Account Engagement tracks many kinds of visitor and prospect activities, and these different kinds of activities contain different kinds of information. For example, an activity created when a prospect opens an email contains the subject and ID of the email. The activity created when a visitor views a landing page contains the name and ID of the landing page.

The XML response to every visitor activity request has the following general format:

TagDescription
<result>Contains the activities that match the parameters specified in your request.
<total_results>Contains the number of activities selected by the request. The query request returns a maximum of 200 activities. If your request matches more than 200 activities, use multiple requests to retrieve all matching activities.
<visitor_activity>The information for an individual visitor activity. See Visitor Activity in Object Field References.

Account Engagement creates an activity when a visitor or prospect interacts with a web page, for example by viewing a form or clicking an advertisement. This table shows the values that a web activity can have for the type field:

ValueActivity Type
1Click
2View
3Error
4Success
5Visitor/Session
7Search
20Visit
21Custom URL Click

The information in the details field, and the name of the primary ID field, give you information about the web activity.

typetype_namedetailsPrimary ID
1 (Click)Visit TrackerURL clickedvisit_ID
1 (Click)Landing Page TrackerURL clickedLanding_Page_ID
1 (Click)Paid Ad SearchHeadlinePaid_Search_ID
1 (Click)Form TrackerURL clickedForm_ID
2 (View)Formform nameForm_Id
2 (View)Landing Pagelanding Page NameLanding_Page_ID
2 (View)Filefile nameFile_ID
2 (View)Multivariate Landing Pageselected landing page namemultivariate_test_variation_id
3 (Error)Multivariate Landing Pageselected landing page namemultivariate_test_variation_id
3 (Error)Landing Pagelanding page nameLanding_Page_ID
3 (Error)Form Handlerform handler nameForm_Handler_ID
3 (Error)Formform nameForm_ID
4 (Success)Multivariate Landing Pageselected landing page namemultivariate_test_variation_id
4 (Success)Landing Pagelanding page nameLanding_Page_ID
4 (Success)Form Handlerform handler nameForm_Handler_ID
4 (Success)Formform nameForm_ID
5 (Visitor / Session)Visitor# page views (Visitor)N/A
7 (Search)Site Search Querysearch termssite_search_query_id
20 (Visit)Visit# page views (Session Visit)visit_ID
21 (Custom_URL_Click)Custom Redirectname of redirectCustom_Redirect_ID

When a visitor or prospect fills out a form, Account Engagement creates an activity with type=2 (View) and type_name = Form. The XML response to a visitor activity request for this record contains the name of the form ("Event Registration"), and the form_id (387xx).

Account Engagement creates an activity when it sends an email, or when a visitor or prospect interacts with the email. An email activity can have the following values for the type field:

ValueActivity TypeNotes
1Click
6Sent
11Open
12Unsubscribe_Open
13Bounce
14Spam_Complaint
15Email_Preference_Open
16Opt_In
17Third_Party_Click
35Indirect_Unsubscribe_Open
36Indirect_BounceOccurs when another prospect with the same email address receives a bounce.
37Indirect_Opt_In

The information in the details field and the email_ID field give you information about the email activity. If the email was sent as part of a list email, the list ID is returned in list_email_id field. If the email was created from a template, the template ID is returned in the email_template_id field.

typetype_namedetails
1 (Click)Email TrackerURL Clicked
6 (Sent)EmailEmail Subject
15 (Email_Preference_Open)--
16 (Opt_In)EmailEmail Subject
37 (Indirect_Opt_In)EmailEmail Subject
11 (Open)EmailEmail Subject
12 (Unsubscribe_Open)EmailEmail Subject
35 (Indirect_Unsubscribe_Open)EmailEmail Subject
13 (Bounce)EmailEmail Subject
36 (Indirect_Bounce)EmailEmail Subject
14 (Spam_Complaint)EmailEmail Subject
17 (Third_Party_Click)EmailURL

When a prospect clicks a link in an email, Account Engagement creates an activity with type type=1 and type_name = Email Tracker. The XML response to a visitor activity request for this record contains:

  • The URL of the link in the details field.
  • The ID of the email in the email_id field.
  • The ID of the list from which the email was sent, in the list_email_id field.
  • The ID of the template used to create the email, in the email_template_id.

Account Engagement creates an activity when an opportunity is created, or information on an opportunity changes. XML responses for opportunity activities contain a field called opportunity_id, which contains the ID of the Salesforce opportunity. Opportunity activities don’t contain a details field. An opportunity activity can have the following values for the type and type_name field:

typetype_name
8 (Opportunity_Created)Opportunity Created
9 (Opportunity_Won)Opportunity Won
10 (Opportunity_Lost)Opportunity Lost
18 (Opportunity_Reopen)Opportunity Reopen
19 (Opportunity_Linked)Opportunity Linked
38 (Opportunity_Unlinked)Opportunity Unlinked