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 any order unless specified otherwise.

For all request:

  • 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. Example: Return all activities created after January 1, 2020, use /api/visitorActivity/version/3/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. Example: To return only "click" and "view" activities, use /api/visitorActivity/version/3/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 only use one of these parameters per request.

ParameterDatatypeOptionsDescription
custom_url_onlybooleantrue or falseReturns activities created when a visitor or prospect clicks a custom redirect URL. See "Custom Redirect Reporting" in the Account Engagement Administrator guide. Example: To return only activities created when a user clicked a custom redirect URL, use /api/visitorActivity/version/3/do/query?custom_url_only=true.
email_onlybooleantrue or falseReturns 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_onlybooleantrue or falseReturns activities created when a visitor or prospect opens, views, or downloads a file.
form_onlybooleantrue or falseReturns 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_onlybooleantrue or falseReturns 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_onlybooleantrue or falseReturns 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. Example: To return activities that were created as a result of the campaign with ID 1131xx, use /api/visitorActivity/version/3/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
limitintegerany integer from 1 to 200The number of activities to return. Default value is 200.
offsetinteger<any_positive_integer>The number of activities to omit from the response (the number to "skip over"). Example: 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/3/do/query?sort_by=updated_at&offset=50
outputstringsimple, mobileThe format to use when returning the results of the query. See XML Response.
sort_bystringcreated_at, id, probability, valueThe field by which the results are sorted. See Sorting Options.
sort_orderstringascending, descendingThe sort order. 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.

ValueDefault Sort OrderDescription
created_atdescendingSort the results by the activities' created_at timestamps.
idascendingSort the results by the activities' ID.
prospect_iddescendingSort the results by the activities' related prospect ID.
visitor_iddescendingSort the results by the activities' related visitor ID.
updated_atdescendingSort the results by the activities' updated_at timestamps.

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

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

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. Note" 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. A web activity can have the following values for the type field:

  • 1 (Click)
  • 2 (View)
  • 3 (Error)
  • 4 (Success)
  • 5 (Visitor/Session)
  • 7 (Search)
  • 20 (Visit)
  • 21 (Custom 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:

  • 1 (Click)
  • 6 (Sent)
  • 11 (Open)
  • 12 (Unsubscribe_Open)
  • 13 (Bounce)
  • 14 (Spam_Complaint)
  • 15 (Email_Preference_Open)
  • 16 (Opt_In)
  • 17 (Third_Party_Click)
  • 35 (Indirect_Unsubscribe_Open)
  • 36 (Indirect_Bounce)
  • 37 (Indirect_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 link's URL in the details field.
  • The email's ID 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