Prospect Object

Use the prospect resources to create and delete prospects, and to query and modify their information. Learn more about prospects in Salesforce Help.

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

Creating and Querying Large Numbers of Prospects

To create, update, and upsert large numbers of prospects, see Import. To query large numbers of prospects, see Export. Import and export resources are asynchronous, and are designed to handle large amounts of data while maintaining your system's performance. For more information about working with large amounts of data, see Pardot for Enterprise Accounts.

Prospect Resources

Resource NameOperationDescription
Prospect AssignPOSTAssign or reassign the specified prospect to a Pardot user or group.
Prospect Batch CreatePOSTCreate up to 50 prospects.
Prospect Batch UpdatePOSTUpdate the specified prospects with the information provided.
Prospect Batch UpsertPOSTUpdate and create prospects with the provided information.
Prospect CreatePOSTCreate a prospect record using an email address.
Prospect DeleteDELETEDelete the specified prospect.
Prospect QueryGETRequest information for the prospects that match the specified criteria.
Prospect ReadGETRequest detailed information for a single prospect.
Prospect UpdatePOSTUpdate a prospect's information, including prospect fields, list subscription, and custom fields.
Prospect UpsertPOSTUpdate and create a prospect with the information provided.
Prospect UnassignPOSTUnassigns the specified prospect from a Pardot user or group.

Prospect Assign

Assigns or reassigns the prospect to a specified Pardot user or group. You can specify prospects by their Pardot ID or CRM FID. You can specify users or groups by their Pardot user ID, email address, or Pardot group ID.

Changes to prospect assignment in Pardot aren’t synced to Salesforce. For example, suppose that you use the Pardot API to assign the prospect prospect@sample.com to user Jean. In Salesforce, prospect@sample.com is assigned to Gita. When Pardot and Salesforce sync, prospect@sample.com is still assigned to Gita.

URIs

Parameters

The request must include one of these parameters.

ParameterTypeDescription
user_emailstringThe user or group's email address.
user_idstringThe user's ID.
group_idstringThe group's ID.

Example: Assign a Prospect to a User

Assign the prospect with Pardot ID 10000 to user 56789.

Prospect Unassign

Unassigns the prospect from a Pardot user or group. You can specify prospects by their Pardot ID or CRM FID.

Changes to prospect assignment in Pardot aren’t synced to Salesforce. For example, suppose that you use the Pardot API to assign the prospect prospect@sample.com to user Jean. In Salesforce, prospect@sample.com is assigned to Gita. When Pardot and Salesforce sync, prospect@sample.com is still assigned to Gita.

URIs

Parameters

The request must include one of these parameters.

ParameterTypeDescription
fidstringThe prospect's CRM FID.
idstringThe prospect's ID.

Example: Unassign a Prospect

Unassign the prospect with Pardot ID 100000.

Prospect Batch Create

Create up to 50 prospects in a single request. Use the query variable prospects to specify prospect information.

To create a prospect, only the prospect email address is required - all other parameters are optional. To assign the prospect to a user, include the parameter <user_id>.

URI

Formats

JSON, XML

Parameters

These parameters are optional.

ParameterTypePossible ValuesDescription
formatstringJSON - the array of created prospects is returned in JSON format.The response format. If unspecified, the response is returned in XML.

Response Body

The response contains an array of the prospects that were created. By default, the response format is in XML. To specify JSON response, use the format parameter.

Example: Create Three Prospects

This example creates three prospects and specifies their first and last names. The prospect information is sent in JSON in the request body.

Prospect Batch Update

Updates up to 50 prospects in a single request. Use the query variable prospects to specify prospect information. You can identify the prospects by Pardot ID or CRM FID, but not by email address.

For a list of prospect fields that you can update, see Object Field References.

URI

Formats

JSON, XML

Example: Update Two Prospects

This example updates two prospects:

  • The prospect with Pardot ID equal to 585648xx has their score updated to 50.
  • The prospect with Pardot ID equal to 585648xx has their score updated to 25.

Prospect information is sent in XML in the request body.

Prospect Batch Upsert

Updates and creates up to 50 prospects in a single request. Use the query variable prospects to specify prospect information. Use Pardot ID or CRM FID to specify the prospects to update. Use email address to specify the prospects to create.

Only the prospect email address is required when creating the prospect - all other parameters are optional. To assign the prospects to a user, include the parameter <user_id>.

For information on how to asynchronously upsert large numbers of prospects, see Import.

URI

Formats

JSON, XML

Example: Create and Update Prospects in a Single Request

This example creates the prospect GitaK@sample.com. It also updates the prospect with Pardot ID 585648xx to have a score of 150.

Prospect Create

Create a prospect with the specified email address. The email address is required and other fields are optional. If you don't provide a campaign ID, the new prospect is assigned to the oldest campaign.

URI

Parameters

You can use any prospect field as a parameter. For a list of prospect fields, see Object Field References.

Example: Create a Prospect

Create a prospect with the email address kmandair@sample.com, the first name Kulvir, and the last name Mandair.

Prospect Delete

Removes one or more specified prospects. You can specify prospects by Pardot ID or email address.

URI

Example

Delete the prospect with Pardot ID 58564819.

Prospect Query

Requests top-level information about prospects that match the specified criteria. You can specify which prospects and which fields to request. A maximum of 200 prospects are returned, unless you specify the output as mobile. If you specify the output as mobile, then all prospects are returned.

Note: To request detailed information about a specific prospect, use Prospect Read.

URI

Parameters to Select Prospects

Use these parameters to specify which prospects are returned. Parameters can be used in any combination and any order unless otherwise specified.

Notes:

ParameterDatatypeOptionsDescription
assignedbooleantrue, falseIf true, returns prospects that are assigned to a user or a group. If false, returns unassigned prospects. Example: To request all the unassigned prospects, use /api/prospect/version/4/do/query?assigned=false
assigned_to_userinteger or stringany positive integer or any stringRequests the prospects that are assigned to the specified user. If no prospects are assigned to the specified user, returns 0. Use email address or Pardot ID to specify users. Note: assigned_to_user overrides assigned. Example: To request all the prospects that are assigned to the user with ID=20700xxx, use /api/prospect/version/4/do/query?assigned_to_user=20700xxx
created_afterstringtoday, yesterday, last_7_days, this_month, last_month,<custom_time>Requests prospects created after the specified time. Example: To request prospects created after midnight on January 1, 2020, use /api/prospect/version/4/do/query?created_after=2020-01-01 00:00:00
created_beforestringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Requests prospects created before the specified date and time. Doesn’t include prospects created on the specified date. <custom_time> Example: to request prospects created before today (but not created today), use api/prospect/version/4/do/query?created_before=today
deletedbooleantrue, falseRequests prospects that were deleted. Default value is false. For more information on recovering deleted prospects, see "Deleting and Undeleting Prospects" in Salesforce Help.
grade_equal_tostringA+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, FRequests prospects that have a grade equal to the specified grade. Example: To request prospects that have a grade equal to B+, use api/prospect/version/4/do/query?grade_greater_than=B+
grade_greater_thanstringA+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, FRequests prospects that have a grade greater than the specified grade.
grade_less_thanstringA+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, FRequests prospects that have a grade less than the specified grade. Parameters must be URL-encoded.
id_greater_thanintegerany positive integerRequests prospects that have a Pardot ID greater than the specified number.
id_less_thanintegerany positive integerReturns prospects that have a Pardot ID less than the specified number.
is_starredbooleantrue, falseIf true, requests prospects that are starred. If false, requests prospects that aren’t starred.
last_activity_beforestringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Requests prospects with last_activity_at property earlier than the specified time.
last_activity_afterstringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Requests prospects with a last_activity_at later than the specified time.
last_activity_neverbooleantrue,falseRequests prospects with last_activity_at equal to null.
list_idintegerany positive integerRequests prospects that are on the specified email list. Example: To request prospects that are on the dynamic email list with a Pardot ID of 1263xx, use api/prospect/version/4/do/query?list_id=1263xx
newbooleantrue, falseRequests prospects that aren’t assigned, don't have is_reviewed equal to true, and have a last_activity_at specified. The new parameter overrides the assigned, assigned_to_user, last_activity_at, and last_activity_before parameters.
score_equal_tointegerany integerRequests prospects with a score equal to the specified number.
score_greater_thanintegerany integerRequests prospects with a score greater than the specified integer.
score_less_thanintegerany integerRequests prospects with a score less than the specified integer.
updated_afterstringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Requests prospects that were last updated after the specified time.
updated_beforestringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Selects prospects that were last updated before the specified time.

Parameters to Specify Which Results Are Returned

Use these parameters to specify which prospect fields are returned, and how the prospects are sorted.

ParameterDatatypeOptionsDescription
fieldsarrayany valid field nameThe fields to return. If unspecified, all fields (including default and custom fields) are returned. Example: To return only the industry, campaign, and company fields, use /api/prospect/version/4/do/query?fields=industry,campaign_id,company
limitintegerany integer from 1 through 200.The number of prospects to return. Default value is 200.
offsetintegerany positive integerThe number of prospects to omit from the response (the number to "skip over"). Example: Retrieve a list of prospects, omitting the 50 most recently updated prospects. Sort the query by the updated_at field and use offset=50: api/prospect/version/4/do/query?sort_by=updated_at&offset=50
outputstringsimple, mobileThe format to be used when returning the results of the query. See XML Response.
sort_bystringcreated_at, id, probability, valueThe field by which the results are sorted. See Sort Order.
sort_orderstringascending, descendingThe sort order. The default value depends on which sort_by parameter you specify. See Sort Order.

Sort Order

Use the sort_by parameter to specify which field Pardot uses to sort the results. Different fields have different default sort orders.

ValueDefault Sort OrderDescription
created_atdescendingSort the results by the prospects' created_at timestamps.
idascendingSort the results by the prospects' id fields.
last_activity_atdescendingSort the results by the prospects' last_activity_at timestamps.
updated_atdescendingSort the results by the prospects' updated_at timestamps.

Prospect Read

Requests detailed information for the specified prospect, including information from the records of related objects. You can specify the prospect by Pardot ID, CRM FID, or email address. Returned information includes values from the prospect record along with these values:

  • the Pardot ID and name of the Pardot campaigns to which the prospect is assigned
  • the prospect profile
  • all visitor activities
  • email list subscriptions
  • information for all custom fields

A prospect can have many visitor activity records. To limit the number of records from related objects that are returned, use limit_related_records. For more information on the XML response, see XML Response for Prospect Read.

URI

Example

Request the information for the prospect with email user1@email.com.

Prospect Update

Updates information for the specified prospect. You can specify prospect by Pardot ID, CRM FID, or email address. Fields that aren’t specified in the request aren’t changed. To clear a field, submit a parameter with no value.

Returns an updated version of the prospect.

Updating multi-value fields

You can update a multi-value field, such as a checklist, by specifying all the values in the multi-value field. The values that you specify replace all existing values. Use an index to specify the value to update:

<field_name>_<N>=<value>

Where <N> is the zero-based index of the value to update.

Add or remove a prospect to or from an email list

You can add or remove a prospect from an email list using the list ID. To add a prospect to a list:

list_<list_id>=1

To remove a prospect from a list:

list_<list_id>=0.

URIs

Parameters

The following parameters can be used in a prospect update request:

  • Any prospect field name, including custom field names.
  • list_<list_id>=0
  • list_<list_id>=1

Example: Update a Prospect's Job Title

To update a prospect's job title to Senior Product Marketing Director, use the parameter-value pair job_title=Product Marketing Director:

Example: Remove a Prospect from an Email List

Remove the prospect (with Pardot ID equal to 10000) from the email list (with email list ID 12345).

Prospect Upsert

Creates a prospect or updates information for the specified prospect. You can specify prospect by Pardot ID, CRM FID, or email address. Specifying by email address always creates a prospect. Fields that aren’t specified in the request aren’t changed. To clear a field, submit a parameter with no value. It's efficient to use upsert instead of update in cases where you're not sure whether the prospect exists or not.

Returns an updated version of the prospect.

URIs

Parameters

The following parameters can be used in a prospect upsert request:

  • Any prospect field name, including custom field names.

Example: Update a Prospect's Job Title

To update a prospect's job title to Senior Product Marketing Director, use the parameter-value pair job_title=Product Marketing Director:

XML Response

The XML response for a query request contains top-level information for multiple prospects. The XML response for a read request contains both top-level and detailed information for a single prospect.

XML Response for Prospect Query

Use prospect query to return top-level information for prospects. Use prospect read to return detailed information about a single prospect.

XML Response Format

Description of XML Response Tags

TagDescription
<result>Contains the prospects that match the parameters specified in your query.
<total_results>Contains the number of prospects selected by the query. Note The query request returns a maximum of 200 prospects. If your query matches more than 200 prospects, you can make several requests to retrieve all matching prospects.
<prospect>The information for an individual Prospect. See the Prospect entry in the Object Field Reference for complete descriptions. Note: Information from related objects including the prospect's profile criteria matchings, visitor activities, and list subscriptions aren’t returned. To retrieve that information, use the read request for a specific prospect.

XML Response for Prospect Read

Use prospect read to return detailed information about a single prospect. Use prospect query to return top-level information for a list of prospects. A read response includes the same information as a query response, plus the prospect's profile criteria, visits, visitor activities, and list subscriptions.

XML Response Formats

The XML response depends on whether you specify output=full, output=simple, or output=mobile. See Description of XML Response Tags for more information about the tags.

XML response for output=full:

The XML response for output=simple:

The XML response for output=mobile:

This response can return more than 200 records.

Description of XML Response Tags

The XML response contains top-level information, plus information from related records.

TagDescription
<prospect>Parent tag. Contains data fields for the target prospect (including custom fields). For complete field listing, see Prospect in Object Field References.
<value>Child tag of data fields with multiple values. Only appears on custom fields that have multiple values.
<campaign>Contains <id> and <name> of the campaign to which this prospect has been assigned. This leaf only appears if the prospect has been assigned to a campaign.
<assigned_to>Contains a <user> node detailing the user to whom this prospect has been assigned. This leaf only appears if the prospect has been assigned to a user. See User in Object Field References.
<last_activity>Contains a <visitor_activity> node detailing this prospect's most recent activity. This leaf only appears if the prospect has visitor activities associated with it. For complete field listing, see Visitor Activity in Object Field References.
<profile>Contains all data fields for the profile associated with this prospect. Also contains several <profile_criteria> tags. For complete field listing, see Profile in Object Field References.
<profile_criteria>Contains all data fields for the profile criteria associated with the prospect's assigned profile. For complete field listing, see Profile Criteria in Object Field References.
<visitors>Contains all visitors associated with this prospect. Contains only <visitor> tags.
<visitor>Contains data fields for a visitor activity, and an <identified_company> and a <visitor_referrer> tag. For complete field listing, see Visitor in Object Field References.
<identified_company>Contains data fields for a visitor's identified company. For complete field listing, see Identified Company in Object Field References.
<visitor_referrer>Contains data fields for a visitor's referrer. For complete field listing, see Visitor Referrer in Object Field References.
<visitor_activities>Contains all visitor activities associated with the prospect. Contains <visitor_activity> tags only.
<visitor_activity>Contains data fields for a visitor activity. For complete field listing, see Visitor Activity in Object Field References.
<lists>Contains all email list subscriptions for this prospect. Contains <list_subscription> tags only.
<list_membership>Contains data fields for an email list subscription, and a <list> tag. For complete field listing, see Email List Membership in Object Field References.
<list>Contains data fields for a list. For complete field listing, see List in Object Field References.