Visitor Activity Resources

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

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

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

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 Pardot ID.

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

URI

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

Example

Return the information for the activity with Pardot ID 153879xxx.

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

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

URI

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

For all request:

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. Example: 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 a Pardot ID greater than the specified integer.
id_less_than integer any positive integer Returns activities with a Pardot 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 Pardot.
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. 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.

Note: you can only use one of these parameters per request.

Parameter Datatype Options Description
custom_url_only boolean true or false Returns activities created when a visitor or prospect clicks a custom redirect URL. See "Custom Redirect Reporting" in the Pardot Administrator guide. 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 true or false 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 true or false Returns activities created when a visitor or prospect opens, views, or downloads a file.
form_only boolean true or false Returns activities created when a visitor or prospect interacts with a form on a Pardot landing page. Interaction includes activities like viewing, filling out, and submitting a form.
form_handler_only boolean true or false Returns activities created when a visitor or prospect interacts with a form in a form handler, typically not hosted on a Pardot landing page. Interaction includes activities like viewing, filling out, and submitting a form.
landing_page_only boolean true or false Returns activities created when a visitor or prospect interacts with a Pardot 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.

Parameter Datatype Options Description
campaign_id integer any valid campaign ID Returns 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/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 Description
limit integer any integer from 1 to 200 The number of activities to return. Default value is 200.
offset integer <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/4/do/query?sort_by=updated_at&offset=50
output string simple, mobile The format to use when returning the results of the query. See XML Response.
sort_by string created_at, id, probability, value The field by which the results are sorted. See Sorting Options.
sort_order string ascending, descending The sort order. 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 Default Sort Order Description
created_at descending Sort the results by the activities' created_at timestamps.
id ascending Sort the results by the activities' ID.
prospect_id descending Sort the results by the activities' related prospect ID.
visitor_id descending Sort the results by the activities' related visitor ID.
updated_at descending Sort the results by the activities' updated_at timestamps.

Examples

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

/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:

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

Pardot 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:

<rsp stat="ok" version="1.0">
    <result>
        <total_results>...</total_results>
        <visitor_activity>
           ...
        </visitor_activity>
    </result>
</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. 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.

XML Response to Web Activities

Pardot 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:

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

<visitor_activity>
    <id>1000000</id>
    <visitor_id>12345</visitor_id>
    <prospect_id>5678910</prospect_id>
    <type>2</type>
    <type_name>Form</type_name>
    <details>Event Registration</details>
    <form_id>5000</form_id>
    <form>
        <name>Event Registration</name>
        <app_url>https://pi.pardot.com/form/read?id=38758</app_url>
    </form>
    <campaign>
        <id>20000</id>
        <name>Webinar Email Opt-In</name>
    </campaign>
    <created_at>2021-07-07 02:59:30</created_at>
    <updated_at>2021-04-26 02:59:30</updated_at>
</visitor_activity>

XML Response to Email Activities

Pardot 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:

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, Pardot creates an activity with type type=1 and type_name = Email Tracker. The XML response to a visitor activity request for this record contains:

<visitor_activity>
    <id>10000</id>
    <prospect_id>1234567</prospect_id>
    <type>1</type>
    <type_name>Email Tracker</type_name>
    <details>http://lenoxsoft.com/#home</details>
    <email_id>987654</email_id>
    <email>
        <name>Monthly Newsletter</name>
        <app_url>https://pi.pardot.com/tracker/read?id=36466xxx&amp;email_id=81269xxx</app_url>
    </email>
    <list_email_id>99999</list_email_id>
    <email_template_id>88888</email_template_id>
    <created_at>2021-07-04 02:35:03</created_at>
    <updated_at>2021-04-26 02:35:03</updated_at>
</visitor_activity>

XML Response to Opportunity Activities

Pardot 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