Querying Visitor Activities
Supported Operations
Operation | URL Format | Required Parameters | Description |
---|---|---|---|
query |
/api/visitorActivity/version/4/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 and/or order unless otherwise specified. 200 visitor activities will be 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. |
- Only one object type filter can be applied at once
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/4/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. |