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.

The API access to the Prospect object follows the conventions described in Version 5 Overview.

Supported Operations

Operation	HTTP Verb	URL Format	Ability Requirements
Create	`POST`	`https://pi.pardot.com/api/v5/objects/prospects`	Prospect > Prospects > Create
Read	`GET`	`https://pi.pardot.com/api/v5/objects/prospects/<id>?<params>`	Prospect > Prospects > View
Update	`PATCH`	`https://pi.pardot.com/api/v5/objects/prospects/<id>`	Prospect > Prospects > Create
Query	`GET`	`https://pi.pardot.com/api/v5/objects/prospects?<params>`	Prospect > Prospects > View
Delete	`DELETE`	`https://pi.pardot.com/api/v5/objects/prospects/<id>`	Prospect > Prospects > Delete
Upsert (Record with Latest Activity At by Email)	`POST`	`https://pi.pardot.com/api/v5/objects/prospects/do/upsertLatestByEmail`	Prospect > Prospects > Create
Undelete (Record in deleted state with Latest Activity At by Email)	`POST`	`https://pi.pardot.com/api/v5/objects/prospects/do/undelete`	Prospect > Prospects > Delete
Add Tag	`POST`	`https://pi.pardot.com/api/v5/objects/prospects/<id>/do/addTag`	Prospect > Prospects > Create AND Marketing > Segmentation > Tags > Create
Remove Tag	`POST`	`https://pi.pardot.com/api/v5/objects/prospects/<id>/do/removeTag`	Prospect > Prospects > Create AND Marketing > Segmentation > Tags > Create

To view or work with prospects not assigned to the API user, the user needs the Prospects > Prospects > View prospects not assigned to self ability.

Note

Fields

Required Editable Fields

Field	Type	Description
`email`	String	Prospect’s email address.

Optional Editable Fields

Field	Type	Description
`addressOne`	String	Prospect’s address, line 1.
`addressTwo`	String	Prospect’s address, line 2.
`annualRevenue`	String	Prospect’s annual revenue.
`campaignId`	Integer	Account Engagement campaign related to this object.
`city`	String	Prospect’s city.
`comments`	String	Comments about this prospect.
`company`	String	Prospect’s company.
`country`	String	Prospect’s country.
`department`	String	Prospect’s department.
`employees`	String	Prospect’s number of employees.
`fax`	String	Prospect’s fax number.
`firstName`	String	Prospect’s first name.
`industry`	String	Prospect’s industry.
`isDoNotCall`	Boolean	If true, prospect prefers not to be called.
`isDoNotEmail`	Boolean	If true, prospect prefers not to be emailed.
`isReviewed`	Boolean	If true, prospect has been reviewed.
`isStarred`	Boolean	If true, prospect has been starred.
`jobTitle`	String	Prospect’s job title.
`lastName`	String	Prospect’s last name.
`notes`	String	Notes about this prospect.
`optedOut`	Boolean	If true, prospect has opted out of marketing communications.
`phone`	String	Prospect’s phone number.
`prospectAccountId`	Integer	Prospect’s account ID. Can be specified only if there’s no CRM connector.
`salesforceId`	String	Salesforce Id of the object. Is unique to a single prospect, so it can’t be specified for multiple prospects.
`salesforceOwnerId`	Integer	Salesforce user that the prospect record is owned by. You must have the Prospects > Prospects > Assign ability to specify this field. You can specify either userId or salesforceOwnerId in a request.
`salutation`	String	Prospect’s formal prefix.
`score`	Integer	Prospect’s score.
`source`	String	Prospect’s source.
`state`	String	Prospect’s US state.
`territory`	String	Prospect’s territory.
`userId`	Integer	User the prospect is assigned to. You must have the Prospects > Prospects > Assign ability to specify this field. You can specify either userId or salesforceOwnerId in a request.
`website`	String	Prospect’s website URL.
`yearsInBusiness`	String	Prospect’s number of years in business.
`zip`	String	Prospect’s postal code.
`profileId`	Integer	Account Engagement profile related to this object.

Read-Only Fields

Field	Type	Description
`id`	Integer	ID of the object.
`campaignParameter`	String	Prospect’s campaign parameter utm_campaign from Google Analytics.
`salesforceCampaignId`	String	The alpha-numeric Id of the associated campaign in the Salesforce Org.
`contentParameter`	String	Prospect’s content parameter utm_content from Google Analytics.
`convertedAt`	DateTime	Time when prospect was converted from visitor.
`convertedFromObjectName`	String	Name of object associated with visitor activity that resulted in prospect being converted from visitor.
`convertedFromObjectType`	String	Type of object associated with visitor activity that resulted in prospect being converted from visitor. Supported values include ‘Form’, ‘FormHandler’, ‘LandingPage’, ‘MultivariateTestVariation’, and ‘Video’.
`doNotSell`	Boolean	Indicates whether the prospect, or a visitor associated with the propect, recorded an activity with the Global Privacy Control Header enabled.
`salesforceAccountId`	String	Account ID in a supported Salesforce system.
`salesforceContactId`	String	Prospect’s contact ID in a supported Salesforce system.
`salesforceLastSync`	DateTime	Last time this prospect was synced with a supported Salesforce system.
`salesforceLeadId`	String	Prospect’s lead ID in a supported Salesforce system.
`emailBouncedAt`	DateTime	Time when prospect email address hard bounced.
`emailBouncedReason`	String	Reason why prospect email address hard bounced.
`firstActivityAt`	DateTime	Time when first visitor activity occurred for this prospect.
`firstAssignedAt`	DateTime	Time prospect was first assigned to a user.
`firstReferrerQuery`	String	First referrer’s search query.
`firstReferrerType`	String	First referrer’s vendor and type (such as ‘Google Natural Search’).
`firstReferrerUrl`	String	First referrer’s URL.
`grade`	String	Prospect’s letter grade.
`isDeleted`	Boolean	True if the object is in the recycle bin in Account Engagement.
`isEmailHardBounced`	Boolean	If true, prospect email address has hard bounced.
`lastActivityAt`	DateTime	Time stamp of this prospect’s latest visitor activity.
`mediumParameter`	String	Prospect’s medium parameter utm_medium from Google Analytics.
`password`	String	Prospect’s password.
`sourceParameter`	String	Prospect’s source parameter utm_source from Google Analytics.
`termParameter`	String	Prospect’s term parameter utm_term from Google Analytics.
`assignedToId`	Integer	User the prospect is assigned to.
`salesforceUrl`	String	URL to view the prospect within the Salesforce system.
`lifecycleStageId`	Integer	Account Engagement lifecycle stage related to this object.
`recentInteraction`	String	Describes the prospect’s most recent interaction with Account Engagement.
`createdAt`	DateTime	Creation time of the object.
`updatedAt`	DateTime	Last update time of the object.
`createdById`	Integer	ID of the user who created this object.
`updatedById`	Integer	ID of the user who last updated this object.
`createdBy`	User	User object representing the user who created this object. See documentation for User for fields.
`updatedBy`	User	User object representing the user who last updated this object. See documentation for User for fields.
`assignedTo`	User	User object representing the user who this object is assigned to. See documentation for User for fields.
`campaign`	Campaign	Campaign object representing the campaign related to this object. See documentation for Campaign for fields.
`prospectAccount`	Prospect Account	Prospect Account object representing the prospect account related to this object. See documentation for Prospect Account for fields.

Requesting Custom Fields

Keep these considerations in mind when requesting custom fields on a prospect record.

The Prospect Query endpoint returns on a subset of custom fields. Multi-select, checkbox, and fields with “Record and display multiple responses” checked aren’t returned.
Prospect Read endpoint returns all custom fields.
Custom fields with the “Number” type in Account Engagement are returned in JSON using the “number” (float) type.
Multi-select, checkbox, and field with “Record and display multiple responses” checked return as arrays. They’re returned as arrays even when there’s a single item.
Custom fields are selected with the “__c” suffix. For example, a field named “Food_Preference” must be selected using “Food_Preference__c” in the API for it to be returned.

Prospect Create

Creates 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.
If the API user doesn’t have the Prospects > Prospects > Assign ability, then the prospect is assigned to the API user.
If the API user has the assign ability, but userId or salesforceOwnerId isn’t specified, the prospect isn’t assigned to any user. Only users with Prospects > Prospects > View prospects not assigned to self ability can view the prospect.
If the API user has the assign ability, they can create the prospect with the userId or salesforceOwnerId in their request. If the prospect is assigned to another user, they can only view the prospect if they have the Prospects > Prospects > View prospects not assigned to self ability.

Example request

1POST /api/v5/objects/prospects?fields=id,firstName,lastName,email HTTP/1.1
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json
5Content-Length: 84
6
7{
8	"email":"a.alexander@sample.com",
9    "firstName": "Athenasius",
10    "lastName": "Alexander"
11}

Example Response

1{
2  "id": 67890,
3  "email": "a.alexandria@sample.com",
4  "firstName": "Athenasius",
5  "lastName": "Alexander"
6}

Prospect Read

Retrieve a single prospect following the conventions described in the Version 5 Overview. To view or work with prospects not assigned to the API user, the user needs the Prospects > Prospects > View prospects not assigned to self ability.

Example request:

1GET /api/v5/objects/prospects/101?fields=id,email,firstName
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example response:

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "id": 101,
5    "email": "jane.doe@example.com",
6    "firstName": "Jane"
7}

Prospect Update

Updating a prospect follows the conventions described in Version 5 Overview. To view or work with prospects not assigned to the API user, the user needs the Prospects > Prospects > View prospects not assigned to self ability.

If the API user can assign prospects, but can’t view prospects not assigned to self, they can update userId or salesforceOwnerId during an update. However, they can’t view the prospect after it’s reassigned.

Note

Prospect Delete

Deleting a prospect follows the conventions described in Version 5 Overview. To view or work with prospects not assigned to the API user, the user needs the Prospects > Prospects > View prospects not assigned to self ability.

Prospect Query

Retrieving a collection of prospect follows the conventions described in Version 5 Overview. To view or work with prospects not assigned to the API user, the user needs the Prospects > Prospects > View prospects not assigned to self ability.

Sortable Fields

When executing a query, the following fields can be specified in the orderBy parameter. See the conventions for query described in the Version 5 Overview.

id
lastActivityAt
createdAt
updatedAt

Example request:

1GET /api/v5/objects/prospects?fields=id,email,firstName
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example response:

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "values": [
5        {
6            "id": 101,
7            "email": "jane.doe@example.com",
8            "firstName": "Jane"
9        }
10    ]
11}

Filtering Results

When executing a query, the following parameters can be used to filter the returned results. These parameters can be specified in the request along with any shared parameters defined in Version 5 Overview. When specifying more than one parameter, all parameters must match the record in order for it to be returned in the results.

Parameter	Description
`id`	Returns any prospects where ID is equal to the given integer value.
`idList`	Returns any prospects where ID is included in the given list of values.
`idGreaterThan`	Returns any prospects where ID is greater than the specified value, non-inclusive.
`idGreaterThanOrEqualTo`	Returns any prospects where ID is greater than or equal to the specified value.
`idLessThan`	Returns any prospects where ID is less than the specified value, non-inclusive.
`idLessThanOrEqualTo`	Returns any prospects where ID is less than or equal to the specified value.
`email`	Returns any prospects where ID is equal to the given string value.
`salesforceId`	Returns any prospects where SalesforceID is equal to the given integer value.
`createdAt`	Returns any prospects where CreatedAt is equal to the given datetime value.
`createdAtAfter`	Returns any prospects where CreatedAt is after the given datetime value, non-inclusive.
`createdAtAfterOrEqualTo`	Returns any prospects where CreatedAt is after or equal to the given datetime value.
`createdAtBefore`	Returns any prospects where CreatedAt is before the given datetime value, non-inclusive.
`createdAtBeforeOrEqualTo`	Returns any prospects where CreatedAt is before or equal to the given datetime value.
`updatedAt`	Returns any prospects where UpdatedAt is equal to the given datetime value.
`updatedAtAfter`	Returns any prospects where UpdatedAt is after the given datetime value, non-inclusive.
`updatedAtAfterOrEqualTo`	Returns any prospects where UpdatedAt is after or equal to the given datetime value.
`updatedAtBefore`	Returns any prospects where UpdatedAt is before the given datetime value, non-inclusive.
`updatedAtBeforeOrEqualTo`	Returns any prospects where UpdatedAt is before or equal to the given datetime value.
`lastActivityAt`	Returns any prospects where LastActivityAt is equal to the given datetime value.
`lastActivityAtAfter`	Returns any prospects where LastActivityAt is after the given datetime value, non-inclusive.
`lastActivityAtAfterOrEqualTo`	Returns any prospects where LastActivityAt is after or equal to the given datetime value.
`lastActivityAtBefore`	Returns any prospects where LastActivityAt is before the given datetime value, non-inclusive.
`lastActivityAtBeforeOrEqualTo`	Returns any prospects where LastActivityAt is before or equal to the given datetime value.
`userId`	Returns any prospects where UserId is equal to the given integer value.
`userIdGreaterThan`	Returns any prospects where UserId is greater than the specified value, non-inclusive.
`userIdGreaterThanOrEqualTo`	Returns any prospects where UserId is greater than or equal to the specified value.
`userIdLessThan`	Returns any prospects where UserId is less than the specified value, non-inclusive.
`userIdLessThanOrEqualTo`	Returns any prospects where UserId is less than or equal to the specified value.
`assignedToId`	Returns any prospects where AssignedToId is equal to the given integer value.
`assignedToIdGreaterThan`	Returns any prospects where AssignedToId is greater than the specified value, non-inclusive.
`assignedToIdGreaterThanOrEqualTo`	Returns any prospects where AssignedToId is greater than or equal to the specified value.
`assignedToIdLessThan`	Returns any prospects where AssignedToId is less than the specified value, non-inclusive.
`assignedToIdLessThanOrEqualTo`	Returns any prospects where AssignedToId is less than or equal to the specified value.
`deleted`	Determines whether to return deleted records. The value can be `false` (default), `true`, or `all`.

Example request:

1GET /api/v5/objects/prospects?fields=id,email,firstName&orderBy=id desc&idGreaterThan=100&idLessThan=200
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example response:

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "values": [
5        {
6            "id": 101,
7            "email": "jane.doe@example.com",
8            "firstName": "Jane"
9        }
10    ]
11}

Prospect Upsert by Email

Prospect upsertLatestByEmail

This procedure updates single prospect with the given email address with the specified prospect fields. If multiple prospects have the given email, the prospect with the latest activity is updated. If there’s no prospect with the given email, a prospect is created.

This procedure works the same as calling the query endpoint. It filters by email address, and if there are no results it creates a prospect with the create endpoint. If prospects are found, it issues a PATCH request on the prospect with the most recent activity.

Prospects that are archived aren’t updated.
If the Prospect update or the Prospect create fails, no records are created or updated.
To view or work with prospects not assigned to the API user, the user needs the Prospects > Prospects > View prospects not assigned to self ability. If the API user doesn’t have this ability, and the last updated prospect isn’t assigned to them, they receive an error.

These properties can be specified in the request body:

MatchEmail: Search for the prospect with this email address. Allows you to change the email address of a given prospect. Prospect: The prospect representation. The email field is always required, and any other optional editable fields can be included. Fields: The fields that are returned in the response. If nothing is specified, only id and email fields are returned. secondaryDeletedSearch: The default is true. When true, the request’s search includes deleted records. This property only affects AMPSEA accounts. If all records with a matching email address are deleted, the one with the latest activity is undeleted and updated. Otherwise, Account Engagement creates a prospect if no prospect with that email address exists.

Example Request

1POST /api/v5/objects/prospects/do/upsertLatestByEmail
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json
5
6{
7    "matchEmail": "tony@avengers.com",
8    "prospect": {
9        "email": "tony@stark.com",
10        "firstName": "Tony"
11     },
12    "fields": ["id", "email", "firstName"], // defaults to "id" and "email" only if not provided
13    "secondaryDeletedSearch": true
14}

Example Response

1{
2  "id": 345,
3  "email": "tony@stark.com",
4  "firstName": "Tony"
5}

Prospect Undelete

Restore a single prospect from the Account Engagement Recycle Bin.

Example Requests

By Prospect ID

1POST /api/v5/objects/prospects/do/undelete HTTP/1.1
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4
5{
6	"id": 71
7}

By Prospect Email Address

1POST /api/v5/objects/prospects/do/undelete HTTP/1.1
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4{
5	"email": "jdoe@company.com"
6}

Example Response

1{
2  "id": 71,
3  "email": "jdoe@company.com",
4  "isDeleted": false
5}

Add Tag

Adds a Tag to the Prospect object, which creates a TaggedObject.

Example Request

1POST https://pi.pardot.com/api/v5/objects/prospects/1000/do/addTag
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json
5
6{
7    "tagId": 100
8}

Example Response

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "id": 610,
5    "createdAt": "2024-09-23T18:26:49-04:00",
6    "createdById": 250,
7    "objectId": 1000,
8    "objectType": "prospect",
9    "tagId": 100
10}

Remove Tag

Remove a tag from a Prospect object. When you remove a tag, the associated TaggedObject record is deleted.

Example Request

1POST https://pi.pardot.com/api/v5/objects/prospects/1000/do/removeTag
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json
5
6{
7    "tagId": 100
8}

Example Response

Returns code 204 no content.