Querying Prospects

Supported Operations

Operation  URL Format  Required Parameters  Description 
query /api/prospect
/version/3
/do/query?...
user_key, api_key Returns the prospects matching the specified criteria parameters. See Using Prospects for complete descriptions of prospect XML Response Formats. Also see Prospect in Object Field References.

Supported Search Criteria

Search criteria may be used together in any combination and/or order unless otherwise specified. Unless output=mobile is specified, 200 prospects will be returned with each query request. This limit is not enforced for responses formatted for mobile devices.

Parameter  Datatype  Options  Description 
assigned boolean true, false Selects prospects based on whether they are assigned.
assigned_to_user integer/string <any_positive_integer>, <any_string> Selects prospects based on whether they are assigned to a specified user. Users can be specified by their email address or their Pardot IDs.

Note: Using assigned_to_user overrides the assigned criteria.
created_after string today, yesterday, last_7_days, this_month, last_month, <custom_time> Selects prospects that were 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 prospects that were created before the specified time. If a <custom_time> is used, ensure that the specified date is formatted using GNU Date Input Syntax.
deleted boolean true, false Selects prospects based on whether they have been deleted.
Default value: false.
grade_equal_to string A+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, F Selects prospects that have a grade equal to the specified grade.

Note: Any value provided for grade_equal_to MUST be URL-encoded.
grade_greater_than string A+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, F Selects prospects that have a grade greater than the specified grade.

Note: Any value provided for grade_greater_than MUST be URL-encoded.
grade_less_than string A+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, F Selects prospects that have a grade less than the specified grade.

Note: Any value provided for grade_less_than MUST be URL-encoded.
id_greater_than integer <any_positive_integer> Selects prospects with IDs greater than the specified integer.
id_less_than integer <any_positive_integer> Selects prospects with IDs less than the specified integer.
is_starred boolean true, false Selects prospects based on whether they are starred.
last_activity_before string today, yesterday, last_7_days, this_month, last_month, <custom_time> Selects prospects that have been active before the specified time. If a <custom_time> is used, ensure that the specified date is formatted using GNU Date Input Syntax. Prospects are considered active if a prospect's last_activity_at is before the specified time. See Prospect in Object Field References.
last_activity_after string today, yesterday, last_7_days, this_month, last_month, <custom_time> Selects prospects that have been active after the specified time. If a <custom_time> is used, ensure that the specified date is formatted using GNU Date Input Syntax. Prospects are considered active if a prospect's last_activity_at is after the specified time. See Prospect in Object Field References.
last_activity_never boolean true Selects prospects that have never been active. Prospects are considered active if a prospect's last_activity_at is null. See Prospect in Object Field References.
list_id integer <any positive integer> Selects prospects based on their membership of the list with the given list_id.
new boolean true, false Selects prospects based on whether they are classified as new. Prospects are considered new if they have not been assigned to a user or a queue, have not been marked as reviewed, and have a last_activity_at timestamp specified. See Prospect in Object Field References.

Note: Using the new criteria overrides the assigned, assigned_to_user, last_activity_at, and last_activity_before criteria if specified.
score_equal_to integer <any_integer> Selects prospects that have a score equal to a specified integer.
score_greater_than integer <any_integer> Selects prospects that have a score greater than a specified integer.
score_less_than integer <any_integer> Selects prospects that have a score less than a specified integer
updated_after string today, yesterday, last_7_days, this_month, last_month, <custom_time> Selects prospects that were last 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 prospects that were last updated before the specified time. If a <custom_time> is used, ensure that the specified date is formatted using GNU Date Input Syntax.

Manipulating the Result Set

Since query result sets are limited to 200 results each, the results returned may not include all prospects that were 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 
fields array <comma_separated_field_ids> Specifies the fields to be returned. Note: If this parameter isn't present, all default fields and custom fields for which the prospect has a value will be returned; <id> will always be returned.
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 prospect(according to the specified sorting order) to be returned in the query response. The first offset matching prospects will be omitted from the response.
Default value: 0.
Example: Specifying offset=400 will return the results starting with the 401st prospect 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 Prospects for more details.
sort_by string created_at, id, probability, value Specifies the field that should be used to sort the results of the query. See Supported Sorting Options for more details.
Default value: id.
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 more 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 Prospect queries, see Prospect in Object Field References.

Value  Default Sort Order  Description 
created_at descending Specifies that the query results should be sorted by the prospects' created_at timestamps.
id ascending Specifies that the query results should be sorted by the prospects' id fields.
last_activity_at descending Specifies that the query results should be sorted by the prospects' last_activity_at timestamps.
updated_at descending Specifies that the query results should be sorted by the prospects' updated_at timestamps.

XML Response Format

<rsp stat="ok" version="1.0">
    <result>  
        <total_results>...</total_results>
        <prospect>...</prospect>
            ...
    </result>
</rsp>
Tag  Description 
<result> Contains the resulting prospects for the specified query.
<total_results> Contains the number of prospects selected by this query. If this value is higher than 200, then several query requests may be necessary to retrieve all matched prospects.
<prospect> The data for an individual Prospect. See Using Prospects for complete descriptions of prospect XML Response Formats. Also see Prospect in Object Field References.

Note: Data concerning a prospect's profile criteria matchings, visitors, visitor activities, and list subscriptions will NOT be included in a query response. To retrieve this data, submit a read request for the prospect of interest.