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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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/<prospect_email>?user_email=<user_email>&api_key=<api_key>&user_key=<user_key>
/api/prospect/version/3/do/assign/email/<prospect_email>?user_id=<user_id>&api_key=<api_key>&user_key=<user_key>
/api/prospect/version/3/do/assign/email/<prospect_email>?group_id=<group_id>&api_key=<api_key>&user_key=<user_key>
/api/prospect/version/3/do/assign/id/<prospect_id>?user_email=<user_email>&api_key=<api_key>&user_key=<user_key>
/api/prospect/version/3/do/assign/id/<prospect_id>?user_id=<user_id>&api_key=<api_key>&user_key=<user_key>
/api/prospect/version/3/do/assign/id/<prospect_id>?group_id=<group_id>&api_key=<api_key>&user_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=<api_key>&user_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=<api_key>&user_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=.
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=<api_key>&user_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=<api_key>&user_key=<user_key>
Note: Checkbox and multi-select fields are the only field types that can be updated in this manner.
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=<api_key>&user_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=<api_key>&user_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=<api_key>&user_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=<prospect_account_id>&api_key=<api_key>&user_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?prospect_account_id=<prospect_account_id>&api_key=<api_key>&user_key=<user_key>
Prospect accounts with an id must exists, and can not be set if a CRM connector is set up in the account.