Querying Prospects
Supported Operations
| Operation | URL Format | Required Parameters | Description |
query |
/api/prospect |
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_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_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. |
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 |
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. |