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.

OperationHTTP VerbURL FormatAbility Requirements
CreatePOSThttps://pi.pardot.com/api/v5/objects/prospectsProspect > Prospects > Create
ReadGEThttps://pi.pardot.com/api/v5/objects/prospects/<id>?<params>Prospect > Prospects > View
UpdatePATCHhttps://pi.pardot.com/api/v5/objects/prospects/<id>Prospect > Prospects > Create
QueryGEThttps://pi.pardot.com/api/v5/objects/prospects?<params>Prospect > Prospects > View
DeleteDELETEhttps://pi.pardot.com/api/v5/objects/prospects/<id>Prospect > Prospects > Delete
Upsert (Record with Latest Activity At by Email)POSThttps://pi.pardot.com/api/v5/objects/prospects/do/upsertLatestByEmailProspect > Prospects > Create
Undelete (Record in deleted state with Latest Activity At by Email)POSThttps://pi.pardot.com/api/v5/objects/prospects/do/undeleteProspect > Prospects > Delete
Add TagPOSThttps://pi.pardot.com/api/v5/objects/prospects/<id>/do/addTagProspect > Prospects > Create AND Marketing > Segmentation > Tags > Create
Remove TagPOSThttps://pi.pardot.com/api/v5/objects/prospects/<id>/do/removeTagProspect > 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.

FieldTypeDescription
emailStringProspect's email address.
FieldTypeDescription
addressOneStringProspect's address, line 1.
addressTwoStringProspect's address, line 2.
annualRevenueStringProspect's annual revenue.
campaignIdIntegerAccount Engagement campaign related to this object.
cityStringProspect's city.
commentsStringComments about this prospect.
companyStringProspect's company.
countryStringProspect's country.
departmentStringProspect's department.
employeesStringProspect's number of employees.
faxStringProspect's fax number.
firstNameStringProspect's first name.
industryStringProspect's industry.
isDoNotCallBooleanIf true, prospect prefers not to be called.
isDoNotEmailBooleanIf true, prospect prefers not to be emailed.
isReviewedBooleanIf true, prospect has been reviewed.
isStarredBooleanIf true, prospect has been starred.
jobTitleStringProspect's job title.
lastNameStringProspect's last name.
notesStringNotes about this prospect.
optedOutBooleanIf true, prospect has opted out of marketing communications.
phoneStringProspect's phone number.
prospectAccountIdIntegerProspect's account ID. Can be specified only if there’s no CRM connector.
salesforceIdStringSalesforce Id of the object. Is unique to a single prospect, so it can't be specified for multiple prospects.
salesforceOwnerIdIntegerSalesforce 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.
salutationStringProspect's formal prefix.
scoreIntegerProspect's score.
sourceStringProspect's source.
stateStringProspect's US state.
territoryStringProspect's territory.
userIdIntegerUser 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.
websiteStringProspect's website URL.
yearsInBusinessStringProspect's number of years in business.
zipStringProspect's postal code.
profileIdIntegerAccount Engagement profile related to this object.
FieldTypeDescription
idIntegerID of the object.
campaignParameterStringProspect's campaign parameter utm_campaign from Google Analytics.
salesforceCampaignIdStringThe alpha-numeric Id of the associated campaign in the Salesforce Org.
contentParameterStringProspect's content parameter utm_content from Google Analytics.
convertedAtDateTimeTime when prospect was converted from visitor.
convertedFromObjectNameStringName of object associated with visitor activity that resulted in prospect being converted from visitor.
convertedFromObjectTypeStringType of object associated with visitor activity that resulted in prospect being converted from visitor. Supported values include 'Form', 'FormHandler', 'LandingPage', 'MultivariateTestVariation', and 'Video'.
doNotSellBooleanIndicates whether the prospect, or a visitor associated with the propect, recorded an activity with the Global Privacy Control Header enabled.
salesforceAccountIdStringAccount ID in a supported Salesforce system.
salesforceContactIdStringProspect's contact ID in a supported Salesforce system.
salesforceLastSyncDateTimeLast time this prospect was synced with a supported Salesforce system.
salesforceLeadIdStringProspect's lead ID in a supported Salesforce system.
emailBouncedAtDateTimeTime when prospect email address hard bounced.
emailBouncedReasonStringReason why prospect email address hard bounced.
firstActivityAtDateTimeTime when first visitor activity occurred for this prospect.
firstAssignedAtDateTimeTime prospect was first assigned to a user.
firstReferrerQueryStringFirst referrer's search query.
firstReferrerTypeStringFirst referrer's vendor and type (such as 'Google Natural Search').
firstReferrerUrlStringFirst referrer's URL.
gradeStringProspect's letter grade.
isDeletedBooleanTrue if the object is in the recycle bin in Account Engagement.
isEmailHardBouncedBooleanIf true, prospect email address has hard bounced.
lastActivityAtDateTimeTime stamp of this prospect's latest visitor activity.
mediumParameterStringProspect's medium parameter utm_medium from Google Analytics.
passwordStringProspect's password.
sourceParameterStringProspect's source parameter utm_source from Google Analytics.
termParameterStringProspect's term parameter utm_term from Google Analytics.
assignedToIdIntegerUser the prospect is assigned to.
salesforceUrlStringURL to view the prospect within the Salesforce system.
lifecycleStageIdIntegerAccount Engagement lifecycle stage related to this object.
recentInteractionStringDescribes the prospect's most recent interaction with Account Engagement.
createdAtDateTimeCreation time of the object.
updatedAtDateTimeLast update time of the object.
createdByIdIntegerID of the user who created this object.
updatedByIdIntegerID of the user who last updated this object.
createdByUserUser object representing the user who created this object. See documentation for User for fields.
updatedByUserUser object representing the user who last updated this object. See documentation for User for fields.
assignedToUserUser object representing the user who this object is assigned to. See documentation for User for fields.
campaignCampaignCampaign object representing the campaign related to this object. See documentation for Campaign for fields.
prospectAccountProspect AccountProspect 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 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

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.

ParameterDescription
idReturns any prospects where ID is equal to the given integer value.
idListReturns any prospects where ID is included in the given list of values.
idGreaterThanReturns any prospects where ID is greater than the specified value, non-inclusive.
idGreaterThanOrEqualToReturns any prospects where ID is greater than or equal to the specified value.
idLessThanReturns any prospects where ID is less than the specified value, non-inclusive.
idLessThanOrEqualToReturns any prospects where ID is less than or equal to the specified value.
emailReturns any prospects where ID is equal to the given string value.
salesforceIdReturns any prospects where SalesforceID is equal to the given integer value.
createdAtReturns any prospects where CreatedAt is equal to the given datetime value.
createdAtAfterReturns any prospects where CreatedAt is after the given datetime value, non-inclusive.
createdAtAfterOrEqualToReturns any prospects where CreatedAt is after or equal to the given datetime value.
createdAtBeforeReturns any prospects where CreatedAt is before the given datetime value, non-inclusive.
createdAtBeforeOrEqualToReturns any prospects where CreatedAt is before or equal to the given datetime value.
updatedAtReturns any prospects where UpdatedAt is equal to the given datetime value.
updatedAtAfterReturns any prospects where UpdatedAt is after the given datetime value, non-inclusive.
updatedAtAfterOrEqualToReturns any prospects where UpdatedAt is after or equal to the given datetime value.
updatedAtBeforeReturns any prospects where UpdatedAt is before the given datetime value, non-inclusive.
updatedAtBeforeOrEqualToReturns any prospects where UpdatedAt is before or equal to the given datetime value.
lastActivityAtReturns any prospects where LastActivityAt is equal to the given datetime value.
lastActivityAtAfterReturns any prospects where LastActivityAt is after the given datetime value, non-inclusive.
lastActivityAtAfterOrEqualToReturns any prospects where LastActivityAt is after or equal to the given datetime value.
lastActivityAtBeforeReturns any prospects where LastActivityAt is before the given datetime value, non-inclusive.
lastActivityAtBeforeOrEqualToReturns any prospects where LastActivityAt is before or equal to the given datetime value.
userIdReturns any prospects where UserId is equal to the given integer value.
userIdGreaterThanReturns any prospects where UserId is greater than the specified value, non-inclusive.
userIdGreaterThanOrEqualToReturns any prospects where UserId is greater than or equal to the specified value.
userIdLessThanReturns any prospects where UserId is less than the specified value, non-inclusive.
userIdLessThanOrEqualToReturns any prospects where UserId is less than or equal to the specified value.
assignedToIdReturns any prospects where AssignedToId is equal to the given integer value.
assignedToIdGreaterThanReturns any prospects where AssignedToId is greater than the specified value, non-inclusive.
assignedToIdGreaterThanOrEqualToReturns any prospects where AssignedToId is greater than or equal to the specified value.
assignedToIdLessThanReturns any prospects where AssignedToId is less than the specified value, non-inclusive.
assignedToIdLessThanOrEqualToReturns any prospects where AssignedToId is less than or equal to the specified value.
deletedDetermines 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

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

Example Request

Example Response

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

Example Request

Example Response

Returns code 204 no content.