Querying Visitor Activities

Supported Operations

Operation URL Format Required Parameters Description
query /api/visitorActivity/version/3/do/query?... user_key, api_key, search_criteria, result_set_criteria Returns the visitor activities that match the specified criteria parameters. See the Using Visitor Activities section for a complete description of visitor activities XML Response Formats. Also see Visitor Activity in Object Field References.

Supported Search Criteria

Search criteria can be used together in any combination or order unless otherwise specified. 200 visitor activities are returned with each query request.

Parameter Datatype Options Description
created_after string today, yesterday, last_7_days, this_month, last_month, <custom_time> Selects visitor activities created after the specified time. If a <custom_time> is used, ensure that the specified date is formatted using GNU Date Input Syntax.
created_before string today, yesterday, last_7_days, this_month, last_month, <custom_time> Selects visitor activities created before the specified time. If a <custom_time> is used, ensure that the specified date is formatted using GNU Date Input Syntax.
id_greater_than integer <any_positive_integer> Selects visitor activities with IDs greater than the specified integer.
id_less_than integer <any_positive_integer> Selects visitor activities with IDs less than the specified integer.
updated_after string today, yesterday, last_7_days, this_month, last_month, <custom_time> Selects visitor activities updated after the specified time. If a <custom_time> is used, ensure that the specified date is formatted using GNU Date Input Syntax.
updated_before string today, yesterday, last_7_days, this_month, last_month, <custom_time> Selects visitor activities updated before the specified time. If a <custom_time> is used, ensure that the specified date is formatted using GNU Date Input Syntax.
prospect_only boolean true or false Selects visitor activities with associated prospects.
type array <comma_separated_visitor_activity_types> Selects visitor activities of the specified types. See a list of available Visitor Activity Types in Visitor Activity in Object Field References.
Object Types
custom_url_only boolean true or false Selects visitor activities associated to custom urls.
email_only boolean true or false Selects visitor activities associated to emails.
file_only boolean true or false Selects visitor activities associated to files.
form_only boolean true or false Selects visitor activities associated to forms.
form_handler_only boolean true or false Selects visitor activities associated to form handlers.
landing_page_only boolean true or false Selects visitor activities associated to landing pages.
Relationships
campaign_id integer <comma_separated_ids> Selects only visitor activities generated by assets whose campaign matches one of the specified Campaign IDs. The IDs should be comma separated positive integers (no spaces). We recommend using a POST request when providing this criteria.
custom_url_id integer <comma_separated_ids> Selects only visitor activities associated with one of the specified custom redirect IDs. The IDs should be comma separated positive integers (no spaces). We recommend using a POST request when providing this criteria.
email_id integer <comma_separated_ids> Selects only visitor activities associated with one of the specified email IDs. The IDs should be comma separated positive integers (no spaces). We recommend using a POST request when providing this criteria.
file_id integer <comma_separated_ids> Selects only visitor activities associated with one of the specified file IDs. The IDs should be comma separated positive integers (no spaces). We recommend using a POST request when providing this criteria.
form_id integer <comma_separated_ids> Selects only visitor activities associated with one of the specified form IDs. The IDs should be comma separated positive integers (no spaces). We recommend using a POST request when providing this criteria.
form_handler_id integer <comma_separated_ids> Selects only visitor activities associated with one of the specified form handler IDs. The IDs should be comma separated positive integers (no spaces). We recommend using a POST request when providing this criteria.
landing_page_id integer <comma_separated_ids> Selects only visitor activities associated with one of the specified landing page IDs. The IDs should be comma separated positive integers (no spaces). We recommend using a POST request when providing this criteria.
prospect_id integer <comma_separated_ids> Selects only visitor activities associated with one of the specified prospect IDs. The IDs should be comma separated positive integers (no spaces). We recommend using a POST request when providing this criteria.
visitor_id integer <comma_separated_ids> Selects only visitor activities associated with one of the specified Visitor IDs. The IDs should be comma separated positive integers (no spaces). We recommend using a POST request when providing this criteria.

Manipulating the Result Set

Since query result sets are limited to 200 results each, the results returned can't include all the visitor activities matched by the query. To retrieve the remaining results, the following criteria can be used to navigate through the result set.

Parameter Datatype Options Description
limit integer <any_positive_integer> Specifies the number of results to be returned. Default value: 200. Note: This number cannot be larger than 200.
offset integer <any_positive_integer> Specifies the first matching visitor according to the specified sorting order to be returned in the query response. The first offset matching visitors are omitted from the response. Default value: 0. Example: Specifying offset=400 will return the results starting with the 401st visitor matched by the provided criteria.
output string simple, mobile Specifies the format to be used when returning the results of the query. See XML Response Formats in Using Visitor Activities for more details.
sort_by string created_at, id, updated_at, prospect_id, visitor_id Specifies the field to be used to sort the results of the query. See Supported Sorting Options for more details.
sort_order string ascending, descending Specifies the ordering to be used when sorting the results of the query. The default value varies based on the value of the sort_by parameter. See Supported Sorting Options for details.

Supported Sorting Options

The ordering of the results returned by a query request can be changed by specifying sort_by and sort_order parameters. Any of the following values are valid when specifying the sort_by parameter. For a complete list of fields involved in visitor activity queries, see VisitorActivity in Object Field References.

Value Default Sort Order Description
created_at descending Specifies that the query results should be sorted by the visitor activities' created_at timestamps.
id ascending Specifies that the query results should be sorted by the visitor activities' id fields.
prospect_id descending Specifies that the query results should be sorted by the visitor activities' related prospects.
visitor_id descending Specifies that the query results should be sorted by the visitor activities' related visitors.
updated_at descending Specifies that the query results should be sorted by the visitor activities' updated_at timestamps.

XML Response Format

<rsp stat="ok" version="1.0">
    <result>
        <total_results>...</total_results>
        <visitor_activity>...</visitor_activity>
            ...
    </result>
</rsp>
Tag Description
<result> Contains the resulting visitor activities for the specified query.
<total_results> Contains the number of visitor activities selected by this query. If this value is higher than 200, then several query requests are sometimes necessary to retrieve all of the matched visitor activities.
<visitor_activity> The data for an individual visitor activity. See Using Visitor Activities for complete descriptions of visitor activity XML Response Formats. Also see Visitor Activity in Object Field References.

Using Visitor Activities

Supported Operations

For a complete list of fields involved in visitor activity operations, see the VisitorActivity section of Object Field References.

Operation URL Format Required Parameters Description
read /api/visitorActivity/version/3/do/read/id/<id>?... user_key, api_key, id Returns the data for the visitor activity specified by <id>. is the Pardot ID for the target visitor activity.

XML Response Formats

<rsp stat="ok" version="1.0">
    <visitor_activity>
        ...
    </visitor_activity>
</rsp>
Tag Description
<visitor_activity> Parent tag. Contains data fields for target visitorActivity. For complete field listing, see Visitor Activity in Object Field References.