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.
Operation | HTTP Verb | URL Format | Ability Requirements |
---|---|---|---|
Create | POST | https://pi.pardot.com/api/v5/objects/prospects | Prospect > Prospects > Create ability |
Read | GET | https://pi.pardot.com/api/v5/objects/prospects/<id>?<params> | Prospect > Prospects > View ability |
Update | PATCH | https://pi.pardot.com/api/v5/objects/prospects/<id> | Prospect > Prospects > Create ability |
Query | GET | https://pi.pardot.com/api/v5/objects/prospects?<params> | Prospect > Prospects > View ability |
Delete | DELETE | https://pi.pardot.com/api/v5/objects/prospects/<id> | Prospect > Prospects > Delete ability |
Upsert (Record with Latest Activity At by Email) | POST | https://pi.pardot.com/api/v5/objects/prospects/do/upsertLatestByEmail | Prospect > Prospects > Create ability |
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 ability |
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.
Field | Type | Description |
---|---|---|
email | String | Prospect's email address. |
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. |
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. |
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.
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
orsalesforceOwnerId
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
orsalesforceOwnerId
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
Example Response
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:
Example response:
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.
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.
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.
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:
Example response:
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:
Example response:
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
Example Response
Restore a single prospect from the Account Engagement Recycle Bin.
Example Requests
By Prospect ID
By Prospect Email Address
Example Response