Using Prospects

Supported Operations

For a complete list of fields involved in Prospect operations, see the Prospect section of Object Field References.

Note: Prospect email addresses cannot be updated using this method.
Operation  URL Format  Required Parameters  Description 
assign /api/prospect
/version/3
/do/assign/
email/<email>?...
user_key, api_key, email, (user_email OR user_id OR group_id) Assigns or reassigns the prospect specified by <email> to a specified Pardot user or group. One (and only one) of the following parameters must be provided to identify the target user or group: <user_email>, <user_id>, or <group_id>. Returns an updated version of the prospect.

Note: Prospect assignments and reassignments do not overwrite existing assignments in CRMs.
assign /api/prospect
/version/3
/do/assign/
id/<id>?...
user_key, api_key, id, (user_email OR user_id OR group_id) Assigns or reassigns the prospect specified by <id> to a specified Pardot user or group. One (and only one) of the following parameters must be provided to identify the target user or group: <user_email>, <user_id>, or <group_id>. Returns an updated version of the prospect.

Note: Prospect assignments and reassignments do not overwrite existing assignments in CRMs.
unassign /api/prospect
/version/3
/do/unassign/
email/<email>?...
user_key, api_key, email Unassigns the prospect specified by <email>. Returns an updated version of the prospect.

Note:Prospect assignments and reassignments do not overwrite existing assignments in CRMs.
unassign /api/prospect
/version/3
/do/unassign/
id/<id>?...
user_key, api_key, id Unassigns the prospect specified by <id>. Returns an updated version of the prospect.

Note: Prospect assignments and reassignments do not overwrite existing assignments in CRMs.
create /api/prospect
/version/3
/do/create/
email/<email>?...
user_key, api_key, email Creates a new prospect using the specified data. <email> must be a unique email address. Email list subscriptions and custom field data may also be added with this request. Refer to the Updating Email List Subscriptions and Updating Field Values sections for more details.
read /api/prospect
/version/3
/do/read/
email/<email>?...
user_key, api_key, email Returns data for the prospect specified by <email>, including campaign assignment, profile criteria matching statuses, associated visitor activities, email list subscriptions, and custom field data. <email> is the email address of the target prospect.
read /api/prospect
/version/3
/do/read/
id/<id>?...
user_key, api_key, id Returns data for the prospect specified by <id>, including campaign assignment, profile criteria matching statuses, associated visitor activities, email list subscriptions, and custom field data. <id> is the Pardot ID of the target prospect.
update /api/prospect
/version/3
/do/update/
email/<email>?...
user_key, api_key, email Updates the provided data for a prospect specified by <email>. <email> is the email address of the prospect. Fields that are not updated by the request remain unchanged. Email list subscriptions and custom field data may also be updated with this request. Refer to the Updating Email List Subscriptions and Updating Field Values sections for more details. Returns an updated version of the prospect.

Note: Prospect email addresses cannot be updated using this method.
update /api/prospect
/version/3
/do/update/
id/<id>?...
user_key, api_key, id Updates the provided data for a prospect specified by <id>. <id> is the Pardot ID of the prospect. Fields that are not updated by the request remain unchanged. Email list subscriptions and custom field data may also be updated with this request. Refer to the Updating Email List Subscriptions and Updating Field Values sections for more details. Returns an updated version of the prospect.
upsert /api/prospect
/version/3
/do/upsert/
email/<email>?...
user_key, api_key, email Updates the provided data for the prospect specified by <email>. If a prospect with the provided email address does not yet exist, a new prospect is created using the <email> value. Fields that are not updated by the request remain unchanged. Email list subscriptions and custom field data may also be updated with this request. Refer to the Updating Email List Subscriptions and Updating Field Values sections for more details. Returns an updated version of the prospect.
upsert /api/prospect
/version/3
/do/upsert/
id/<id>?...
user_key, api_key, (id OR email) Updates the provided data for the prospect specified by <id>. If an <email> value is provided, it is used to update the prospect's email address. If a prospect with the provided ID is not found, Pardot searches for a prospect identified by <email>. If a prospect with the provided email address does not yet exist, a new prospect is created using <email> value. Fields that are not updated by the request remain unchanged. Email list subscriptions and custom field data may also be updated with this request. Refer to the Updating Email List Subscriptions and Updating Field Values sections for more details. Returns an updated version of the prospect.
delete /api/prospect
/version/3
/do/delete/
email/<email>?...
user_key, api_key, email Deletes the prospect specified by <email>. Returns HTTP 204 No Content on success.

Note: Prospects may only be deleted using HTTP methods POST or DELETE.
delete /api/prospect
/version/3
/do/delete/
id/<id>?...
user_key, api_key, id Deletes the prospect specified by <id>. Returns HTTP 204 No Content on success.

Note: Prospects may only be deleted using HTTP methods POST or DELETE.

XML Response Formats

For output=full:

<rsp stat="ok" version="1.0">
    <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>

For output=simple:

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

For output=mobile:

<rsp stat="ok" version="1.0">
    <prospect>   
        <id>...</id>
        <first_name>...</first_name>
        <last_name>...</last_name>
        <email>...</email>
        <company>...</company>
    </prospect>
</rsp>
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 with 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, as well as an <identified_company> and a <visitor_referrer> tag. For complete field listing, see Visitor in Object Field References.
<identified_company> Contains data field 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 this prospect. Contains only <visitor_activity> tags.
<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 only <list_subscription> tags.
<list_subscription> Contains data fields for an email list subscription, as well as a <list> tag. For complete field listing, see Email List Subscription in Object Field References.
<list> Contains data fields for an email list. For complete field listing, see Email List in Object Field References.

Assigning and Reassigning Prospects

To assign/reassign a prospect, both the prospect to be assigned and the target user or group of the assignment must be defined. Prospects can be specified by their Pardot ID or email address. Users or groups can be specified by their Pardot user ID, email address, or Pardot group ID. Possible combinations of parameters are shown below. Developers are responsible for substituting specific values for parameters denoted by <carets>.

Examples:
/api/prospect/version/3/do/assign/email/?user_email=&api_key=&user_key= /api/prospect/version/3/do/assign/email/?user_id=&api_key=&user_key= /api/prospect/version/3/do/assign/email/?group_id=&api_key=&user_key= /api/prospect/version/3/do/assign/id/?user_email=&api_key=&user_key= /api/prospect/version/3/do/assign/id/?user_id=&api_key=&user_key= /api/prospect/version/3/do/assign/id/?group_id=&api_key=&user_key=

XML responses to assign requests are identical to read requests, but reflect the new prospect assignment in the <assigned_to> node.

Creating Prospects

To create a propsect via the API, only a valid and unique email address is required. Values for any other prospect fields may also be provided in the create request. Developers are responsible for substituting specific values for parameters denoted by <carets>.

Example: Creating a new prospect /api/prospect/version/3/do/create/email/new_prospect@pardot.com?first_name=New&last_name=Prospect&api_key=&user_key=

XML responses to create requests are identical to update and read requests. If no campaign_id value is provided, the new prospect will be automatically assigned to the oldest existing campaign.

Updating Field Values

Modifying values of prospect data fields is done by submitting an update request with parameters for each field to be updated. Each parameter is formatted as <field_name>=<value>. Custom field values are updated using the same syntax.

Example: Updating the phone number of a prospect whose email address is bob@pardot.com: /api/prospect/version/3/do/update/email/bob@pardot.com?phone=888-123-4567&api_key=&user_key=

Only values that are specifically named in the request are updated. All others are left unchanged. To clear a value, submit an update request containing a parameter with no specified value, such as phone=. Note: Any field that is set to record multiple responses cannot have its values cleared this way.

Updating Fields with Predefined Values

Modifying values of prospect data fields with predefined values is accomplished through an update request with parameters for each field to be updated. Each parameter is formatted as <field_name>=<value> where <value> matches the predefined field value. Custom field values are updated using the same syntax.

Example: Updating the category of a prospect whose email address is bob@pardot.com *to the category consumer: /api/prospect/version/3/do/update/email/bob@pardot.com?category=consumer&api_key=&user_key=

Updating Fields with Multiple Values

Updating field values with multiple values follows the same convention as fields with predefined values, but requires a different parameter naming scheme to allow multiplicity. An update request is submitted with parameters formatted as <field_name>_<count>=<field_value> where <count> is an integer denoting the current parameter's place in sequence. <count> must start at 0 and increase by 1 until all desired values are submitted.

Example: Modifying the values of a custom field with field name past_jobs for a prospect with a Pardot ID of 5: /api/prospect/version/3/do/update/id/5?past_jobs_0=janitor&past_jobs_1=security&api_key=&user_key=

Note: Checkbox and multi-select fields are the only field types that can be updated in this manner. To clear all of the values for a checkbox or multi-select field, use <field_name>_0=. To clear specific values, just set the values that should remain in the prospect record using the method above.

Updating Email List Subscriptions

To modify email list subscriptions for a prospect, the Pardot ID of the email list is required. Once the ID is obtained, an update is submitted with parameters formatted as list_<list_id>=1 to create a subscription and list_<list_id>=0 to end a subscription.

Example: Adding a prospect whose email address is bob@pardot.com to an email list with Pardot ID 8: /api/prospect/version/3/do/update/email/bob@pardot.com?list_8=1&api_key=&user_key=

Requests that attempt to subscribe a prospect to lists that it is already subscribed to are ignored. Unsubscribe requests are handled similarly.

Updating Profile Criteria Matching Statuses

To modify a prospect's matching status for associated profile criteria, the Pardot ID of the profile criteria is required. Once the ID is obtained, an update is submitted with parameters formatted as profile_criteria_<profile_criteria_id>=<status>. The value of <status> may be either match, nomatch, or unknown.

Example: Setting a profile criteria for a prospect whose email address is bob@pardot.com to match: /api/prospect/version/3/do/update/email/bob@pardot.com?profile_criteria_8=match&api_key=&user_key=Example: Setting a profile criteria for a prospect with Pardot ID 58 to nomatch: /api/prospect/version/3/do/update/id/58?profile_criteria_8=nomatch&api_key=&user_key=

Only profile criteria that belong to the profile associated with the prospect can be updated using this method. Requests to update profile criteria not associated with the assigned profile will be ignored. Using any matching status values other than match, nomatch, or unknown will result in an error message. See Error Codes & Messages for details.

Updating Prospect Account Associations

To modify a prospect's matching status for associated prospect account, the Pardot ID of the prospect account is required. Once the ID is obtained, an update is submitted with parameters formatted as prospect_account_id=<id>.

Example: Setting a prospect account for a prospect whose email address is bob@pardot.com to match: /api/prospect/version/3/do/update/email/bob@pardot.com?prospect_account_id=&api_key=&user_key=

A prospect account with the id must exist, and can not be set if a CRM connector is set up in the account.