Pardot's developer content is getting a makeover! Starting July 12th, you’ll be redirected to our new site.

Prospect Resources

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

Note: 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.

Resource Name Operation Description
Prospect Assign POST Assign or reassign the specified prospect to a Pardot user or group.
Prospect Batch Create POST Create up to 50 prospects.
Prospect Batch Update POST Update the specified prospects with the information provided.
Prospect Batch Upsert POST Update and create prospects with the provided information.
Prospect Create POST Create a prospect record using an email address.
Prospect Delete DELETE Delete the specified prospect.
Prospect Query GET Request information for the prospects that match the specified criteria.
Prospect Read GET Request detailed information for a single prospect.
Prospect Update POST Update a prospect's information, including prospect fields, list subscription, and custom fields.
Prospect Upsert POST Update and create a prospect with the information provided.
Prospect Unassign POST Unassigns 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.

Note: 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

/api/prospect/version/4/do/assign/id/<id>?...
/api/prospect/version/4/do/assign/ fid/<fid>?...
/api/prospect/version/4/do/assign/email/...

Parameters

The request must include one of these parameters.

Parameter Type Description
user_email string The user or group's email address.
user_id string The user's ID.
group_id string The group's ID.

Example: Assign a Prospect to a User

Assign the prospect with Pardot ID 10000 to user 56789.

/api/prospect/version/4/do/assign/id/10000?user_id=56789

Prospect Unassign

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

Note: 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

/api/prospect/version/4/do/unassign/id/<id>?...
/api/prospect/version/4/do/unassign/ fid/<fid>?...

Parameters

The request must include one of these parameters.

Parameter Type Description
fid string The prospect's CRM FID.
id string The prospect's ID.

Example: Unassign a Prospect

Unassign the prospect with Pardot ID 100000.

/api/prospect/version/4/do/unassign/id/10000

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

/api/prospect/version/4/do/batchCreate

Formats

JSON, XML

Parameters

These parameters are optional.

Parameter Type Possible Values Description
format string JSON - 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.

POST /api/prospect/version/4/do/batchCreate? HTTP/1.1
Host: pi.pardot.com
Authorization: Bearer <ACCESS TOKEN>
Pardot-Business-Unit-Id: <BUSINESS UNIT ID>

prospects={
    "prospects": [
    {"email":"JaneDoe@email.com","first_name":"Jane","last_name":"Doe"},
    {"email":"JSmith@email.com","first_name":"John","last_name":"Smith"},
    {"email":"JillJohns112@email.com","first_name":"Jill","last_name":"Johns"}
    ]
}

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

/api/prospect/version/4/do/batchUpdate

Formats

JSON, XML

Example: Update Two Prospects

This example updates two prospects:

Prospect information is sent in XML in the request body.

Host: pi.pardot.com
Authorization: Bearer <ACCESS TOKEN>
Pardot-Business-Unit-Id: <BUSINESS UNIT ID>

prospects=<prospects>
    <prospect>
        <id>585648xx</id>
        <score>50</score>
    </prospect>
    <prospect>
        <id>58564819</id>
        <score>25</score>
    </prospect>
</prospects>

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

/api/prospect/version/4/do/batchUpsert

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.

POST /api/prospect/version/4/do/batchUpsert? HTTP/1.1
Host: pi.pardot.com
Authorization: Bearer <ACCESS TOKEN>
Pardot-Business-Unit-Id: <BUSINESS UNIT ID>

prospects=<prospects>
    <prospect>
        <id>585648xx</id>
        <score>150</score>
    </prospect>
        <prospect>
        <email>GitaK@sample.com</email>
    </prospect>
</prospects>

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

/api/prospect/version/4/do/create/email<email@email.com>?...

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.

POST /api/prospect/version/4/do/create?format=json HTTP/1.1
Host: pi.pardot.com
Authorization: Bearer <ACCESS TOKEN>
Pardot-Business-Unit-Id: <BUSINESS UNIT ID>

email=kmandair@sample.com&first_name=Kulvir&last_name=Mandair

Prospect Delete

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

URI

/api/prospect/version/4/do/delete/id/<ID>

Example

Delete the prospect with Pardot ID 58564819.

/api/prospect/version/4/do/delete/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

/api/prospect/version/4/do/query/?...

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:

Parameter Datatype Options Description
assigned boolean true, false If 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_user integer or string any positive integer or any string Requests 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_after string today, 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_before string today, 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
deleted boolean true, false Requests 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_to string A+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, F Requests 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_than string A+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, F Requests prospects that have a grade greater than the specified grade.
grade_less_than string A+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, F Requests prospects that have a grade less than the specified grade. Parameters must be URL-encoded.
id_greater_than integer any positive integer Requests prospects that have a Pardot ID greater than the specified number.
id_less_than integer any positive integer Returns prospects that have a Pardot ID less than the specified number.
is_starred boolean true, false If true, requests prospects that are starred. If false, requests prospects that aren’t starred.
last_activity_before string today, yesterday, last_7_days, this_month, last_month, <custom_time> Requests prospects with last_activity_at property earlier than the specified time.
last_activity_after string today, yesterday, last_7_days, this_month, last_month, <custom_time> Requests prospects with a last_activity_at later than the specified time.
last_activity_never boolean true,false Requests prospects with last_activity_at equal to null.
list_id integer any positive integer Requests 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
new boolean true, false Requests 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_to integer any integer Requests prospects with a score equal to the specified number.
score_greater_than integer any integer Requests prospects with a score greater than the specified integer.
score_less_than integer any integer Requests prospects with a score less than the specified integer.
updated_after string today, yesterday, last_7_days, this_month, last_month, <custom_time> Requests prospects that were last updated after the specified time.
updated_before string today, 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.

Parameter Datatype Options Description
fields array any valid field name The 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
limit integer any integer from 1 through 200. The number of prospects to return. Default value is 200.
offset integer any positive integer The 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
output string simple, mobile The format to be used when returning the results of the query. See XML Response.
sort_by string created_at, id, probability, value The field by which the results are sorted. See Sort Order.
sort_order string ascending, descending The 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.

Value Default Sort Order Description
created_at descending Sort the results by the prospects' created_at timestamps.
id ascending Sort the results by the prospects' id fields.
last_activity_at descending Sort the results by the prospects' last_activity_at timestamps.
updated_at descending Sort 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:

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

/api/prospect/version/4/do/read/id/<ID>?..

/api/prospect/version/4/do/read/id/<FID>?..

/api/prospect/version/4/do/read/email/user1@email.com?...

Example

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

/api/prospect/version/4/do/read/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

/api/prospect/version/4/do/update/id/<ID>?...

/api/prospect/version/4/do/update/email/<email>?...

Parameters

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

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:

/api/prospect/version/4/do/update/id/18632076?job_title=Senior 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).

POST /api/prospect/version/4/do/update/id/10000? HTTP/1.1
Host: pi.pardot.com
Authorization: Bearer <ACCESS TOKEN>
Pardot-Business-Unit-Id: <BUSINESS UNIT ID>

list_12345=0

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

/api/prospect/version/4/do/upsert/id/<ID>?...

/api/prospect/version/4/do/upsert/email/<FID>?...

/api/prospect/version/4/do/upsert/email/<email>?...

Parameters

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

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:

POST /api/prospect/version/4/do/upsert/id/10000?format=json HTTP/1.1
Host: pi.pardot.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <ACCESS TOKEN>
Pardot-Business-Unit-Id: <BUSINESS UNIT ID>


salutation=&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

<rsp stat="ok" version="1.0">
    <result>
        <total_results>...</total_results>
        <prospect>...</prospect>
            ...
    </result>
</rsp>

Description of XML Response Tags

Tag Description
<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:

<rsp stat="ok" version="1.0">
<total_results>...</total_results>
    <prospect>
        ...
        <campaign>
            ...
        </campaign>
        <assigned_to>
            ...
        </assigned_to>
        <last_activity>
            ...
        </last_activity>
        <profile>
            ...
            <profile_criteria>
                ...
            </profile_criteria>
        </profile>
        <visitors>
            <visitor>
                ...
                <identified_company>
                    ...
                </identified_company>
                <visitor_referrer>
                    ...
                </visitor_referrer>
            </visitor>
        </visitors>
        <visitor_activities>
            <visitor_activity>
                ...
            </visitor_activity>
        </visitor_activities>
        <lists>
            <list_subscription>
                ...
                <list>
                    ...
                </list>
            </list_subscription>
        </lists>
    </prospect>
</rsp>

The XML response for output=simple:

<rsp stat="ok" version="1.0">
    <prospect>
        ...
        <campaign>
            ...
        </campaign>
        <assigned_to>
            ...
        </assigned_to>
        <last_activity>
            ...
        </last_activity>
    </prospect>
</rsp>

The XML response for output=mobile: Note: This response can return more than 200 records.

<rsp stat="ok" version="1.0">
    <prospect>
        <id>...</id>
        <first_name>...</first_name>
        <last_name>...</last_name>
        <email>...</email>
        <company>...</company>
    </prospect>
</rsp>

Description of XML Response Tags

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

Tag Description
<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.