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.

Note

Visitor Activity Resources

Resource Name	Operation	Description
Visitor Activity Read	`GET`	Returns information for a single visitor activity.
Visitor Activity Query	`GET`	Returns information for up to 200 activities.

Visitor Activity Read

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

URI

1/api/activity/version/4/do/read/id/<ID>?..

Example

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

1/api/visitorActivity/version/4/do/read/id/153879xxx

Visitor Activity Query

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.

URI

1/api/visitorActivity/version/4/do/query

Parameters to Select Activities

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:mm.

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

General Parameters

Parameter	Datatype	Options	Description
`created_after`	String	`today`, `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_before`	String	`today`, `yesterday`, `last_7_days`, `this_month`, `last_month`, `<custom_time>`	Returns activities created before the specified time.
`id_greater_than`	Integer	any positive integer	Returns activities with an Account Engagement ID greater than the specified integer.
`id_less_than`	Integer	any positive integer	Returns activities with an Account Engagement ID less than the specified integer.
`updated_after`	String	`today`, `yesterday`, `last_7_days`, `this_month`, `last_month`, `<custom_time>`	Returns activities updated after the specified time.
`updated_before`	String	`today`, `yesterday`, `last_7_days`, `this_month`, `last_month`, `<custom_time>`	Returns activities updated before the specified time.
`prospect_only`	`boolean`	`true` or `false`	Returns activities for prospects, but not for visitors. Prospects are visitors who have an associated email address in Account Engagement.
`type`	`array`	any valid type of visitor activity	Returns 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`

Request Activities by Category

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.

Note

Parameter	Datatype	Description
`custom_url_only`	`boolean`	Returns 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_only`	`boolean`	Returns 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_only`	`boolean`	Returns activities created when a visitor or prospect opens, views, or downloads a file.
`form_only`	`boolean`	Returns 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_only`	`boolean`	Returns 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_only`	`boolean`	Returns 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.

Request Activities by Related Object

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.

Parameter	Datatype	Options	Description
`campaign_id`	Integer	any valid campaign ID	Returns 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_id`	Integer	any valid custom URL ID	Returns activities associated with the specified custom redirect.
`email_id`	Integer	any valid email ID	Returns activities associated with the specified email.
`file_id`	Integer	any valid file ID	Returns activities associated with the specified file IDs.
`form_id`	Integer	any valid form ID	Returns activities associated with the specified form IDs.
`form_handler_id`	Integer	any valid form handler	Returns activities associated with the specified form handler IDs.
`landing_page_id`	Integer	any valid landing page ID	Returns activities associated with the specified landing page IDs.
`prospect_id`	Integer	any valid prospect ID	Returns activities associated with one of the specified prospect IDs.
`visitor_id`	Integer	any valid visitor ID	Returns activities associated with one of the specified Visitor IDs.

Parameters to Specify Which Results Are Returned

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

Parameter	Datatype	Options
`limit`	Integer	The number of activities to return. The minimum value is 1 and the maximum value is 200. The default value is 200.
`offset`	Integer	The 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`
`output`	String	The format to use when returning the results of the query. Possible values are `simple` and `mobile`. See XML Response.
`sort_by`	String	The field by which the results are sorted. You can sort by `created_at`, `id`, `probability`, or `value`. See Sorting Options.
`sort_order`	String	The sort order. Possible values are `ascending` and `descending`. The default value depends on which `sort_by` parameter you specify. See Sorting Options.

Sorting Options

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

Value	Description
`created_at`	Sort the results by the `created_at` timestamps of the activities. The default sort order is `descending`.
`id`	Sort the results by the IDs of the activities. The default sort order is `ascending`.
`prospect_id`	Sort the results by the related prospect ID of the activities. The default sort order is `descending`.
`visitor_id`	Sort the results by the related visitor ID of the activities. The default sort order is `descending`.
`updated_at`	Sort the results by the `updated_at` timestamps of the activities. The default sort order is `descending`.

Examples

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

1/api/visitorActivity/version/4/do/query?prospect_id=1234xxx,5678xxx

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

1/api/visitorActivity/version/4/do/query?file_only=true&campaign_id=1234

XML Response

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.

General XML Response Format

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

1<rsp stat="ok" version="1.0">
2    <result>
3        <total_results>...</total_results>
4        <visitor_activity>
5           ...
6        </visitor_activity>
7    </result>
8</rsp>

Description of XML Response Tags

Tag	Description
`<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.

XML Response to Web Activities

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:

Value	Activity Type
`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.

`type`	`type_name`	`details`	Primary ID
1 (Click)	Visit Tracker	URL clicked	visit_ID
1 (Click)	Landing Page Tracker	URL clicked	Landing_Page_ID
1 (Click)	Paid Ad Search	Headline	Paid_Search_ID
1 (Click)	Form Tracker	URL clicked	Form_ID
2 (View)	Form	form name	Form_Id
2 (View)	Landing Page	landing Page Name	Landing_Page_ID
2 (View)	File	file name	File_ID
2 (View)	Multivariate Landing Page	selected landing page name	multivariate_test_variation_id
3 (Error)	Multivariate Landing Page	selected landing page name	multivariate_test_variation_id
3 (Error)	Landing Page	landing page name	Landing_Page_ID
3 (Error)	Form Handler	form handler name	Form_Handler_ID
3 (Error)	Form	form name	Form_ID
4 (Success)	Multivariate Landing Page	selected landing page name	multivariate_test_variation_id
4 (Success)	Landing Page	landing page name	Landing_Page_ID
4 (Success)	Form Handler	form handler name	Form_Handler_ID
4 (Success)	Form	form name	Form_ID
5 (Visitor / Session)	Visitor	# page views (Visitor)	N/A
7 (Search)	Site Search Query	search terms	site_search_query_id
20 (Visit)	Visit	# page views (Session Visit)	visit_ID
21 (Custom_URL_Click)	Custom Redirect	name of redirect	Custom_Redirect_ID

Example

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).

1<visitor_activity>
2    <id>1000000</id>
3    <visitor_id>12345</visitor_id>
4    <prospect_id>5678910</prospect_id>
5    <type>2</type>
6    <type_name>Form</type_name>
7    <details>Event Registration</details>
8    <form_id>5000</form_id>
9    <form>
10        <name>Event Registration</name>
11        <app_url>https://pi.pardot.com/form/read?id=38758</app_url>
12    </form>
13    <campaign>
14        <id>20000</id>
15        <name>Webinar Email Opt-In</name>
16    </campaign>
17    <created_at>2021-07-07 02:59:30</created_at>
18    <updated_at>2021-04-26 02:59:30</updated_at>
19</visitor_activity>

XML Response to Email Activities

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:

Value	Activity Type	Notes
`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	Occurs when another prospect with the same email address receives a 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.

`type`	`type_name`	`details`
`1` (Click)	Email Tracker	URL Clicked
`6` (Sent)	Email	Email Subject
`15` (Email_Preference_Open)	-	-
`16` (Opt_In)	Email	Email Subject
`37` (Indirect_Opt_In)	Email	Email Subject
`11` (Open)	Email	Email Subject
`12` (Unsubscribe_Open)	Email	Email Subject
`35` (Indirect_Unsubscribe_Open)	Email	Email Subject
`13` (Bounce)	Email	Email Subject
`36` (Indirect_Bounce)	Email	Email Subject
`14` (Spam_Complaint)	Email	Email Subject
`17` (Third_Party_Click)	Email	URL

Example

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.

1<visitor_activity>
2    <id>10000</id>
3    <prospect_id>1234567</prospect_id>
4    <type>1</type>
5    <type_name>Email Tracker</type_name>
6    <details>http://lenoxsoft.com/#home</details>
7    <email_id>987654</email_id>
8    <email>
9        <name>Monthly Newsletter</name>
10        <app_url>https://pi.pardot.com/tracker/read?id=36466xxx&amp;email_id=81269xxx</app_url>
11    </email>
12    <list_email_id>99999</list_email_id>
13    <email_template_id>88888</email_template_id>
14    <created_at>2021-07-04 02:35:03</created_at>
15    <updated_at>2021-04-26 02:35:03</updated_at>
16</visitor_activity>

XML Response to Opportunity Activities

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:

type	type_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