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.

Include the authentication header with every request. For information on how to authenticate, see Authentication.

To create, update, and upsert large numbers of prospects, see Import. To query large numbers of prospects, see Export. Import and export resources are asynchronous, and are designed to handle large amounts of data while maintaining your system's performance. For more information about working with large amounts of data, see Account Engagement for Enterprise Accounts.

Resource NameOperationDescription
Prospect AssignPOSTAssign or reassign the specified prospect to an Account Engagement user or group.
Prospect Batch CreatePOSTCreate up to 50 prospects.
Prospect Batch UpdatePOSTUpdate the specified prospects with the information provided.
Prospect Batch UpsertPOSTUpdate and create prospects with the provided information.
Prospect CreatePOSTCreate a prospect record using an email address.
Prospect DeleteDELETEDelete the specified prospect.
Prospect QueryGETRequest information for the prospects that match the specified criteria.
Prospect ReadGETRequest detailed information for a single prospect.
Prospect UpdatePOSTUpdate a prospect's information, including prospect fields, list subscription, and custom fields.
Prospect UpsertPOSTUpdate and create a prospect with the information provided.
Prospect UnassignPOSTUnassigns the specified prospect from an Account Engagement user or group.

Assigns or reassigns the prospect to a specified Account Engagement user or group. You can specify prospects by their Account Engagement ID or CRM FID. You can specify users or groups by their Account Engagement user ID, email address, or Account Engagement group ID.

Changes to prospect assignment in Account Engagement aren’t synced to Salesforce. For example, suppose that you use the Account Engagement API to assign the prospect prospect@sample.com to user Jean. In Salesforce, prospect@sample.com is assigned to Gita. When Account Engagement and Salesforce sync, prospect@sample.com is still assigned to Gita.

The request must include one of these parameters.

ParameterTypeDescription
user_emailstringThe user or group's email address.
user_idstringThe user's ID.
group_idstringThe group's ID.

Assign the prospect with Account Engagement ID 10000 to user 56789.

Unassigns the prospect from an Account Engagement user or group. You can specify prospects by their Account Engagement ID or CRM FID.

Changes to prospect assignment in Account Engagement aren’t synced to Salesforce. For example, suppose that you use the Account Engagement API to assign the prospect prospect@sample.com to user Jean. In Salesforce, prospect@sample.com is assigned to Gita. When Account Engagement and Salesforce sync, prospect@sample.com is still assigned to Gita.

The request must include one of these parameters.

ParameterTypeDescription
fidstringThe prospect's CRM FID.
idstringThe prospect's ID.

Unassign the prospect with Account Engagement ID 100000.

Create up to 50 prospects in a single request. Use the query variable prospects to specify prospect information.

To create a prospect, only the prospect email address is required - all other parameters are optional. To assign the prospect to a user, include the parameter <user_id>.

JSON, XML

These parameters are optional.

ParameterTypePossible ValuesDescription
formatstringJSON - the array of created prospects is returned in JSON format.The response format. If unspecified, the response is returned in XML.

The response contains an array of the prospects that were created. By default, the response format is in XML. To specify JSON response, use the format parameter.

This example creates three prospects and specifies their first and last names. The prospect information is sent in JSON in the request body.

Updates up to 50 prospects in a single request. Use the query variable prospects to specify prospect information. You can identify the prospects by Pardot ID or CRM FID, but not by email address.

For a list of prospect fields that you can update, see Object Field References.

JSON, XML

This example updates two prospects:

  • The prospect with Account Engagement ID equal to 585648xx has their score updated to 50.
  • The prospect with Account Engagement ID equal to 585648xx has their score updated to 25.

Prospect information is sent in XML in the request body.

Updates and creates up to 50 prospects in a single request. Use the query variable prospects to specify prospect information. Use Account Engagement ID or CRM FID to specify the prospects to update. Use email address to specify the prospects to create.

Only the prospect email address is required when creating the prospect - all other parameters are optional. To assign the prospects to a user, include the parameter <user_id>.

For information on how to asynchronously upsert large numbers of prospects, see Import.

JSON, XML

This example creates the prospect GitaK@sample.com. It also updates the prospect with Account Engagement ID 585648xx to have a score of 150.

Create 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.

You can use any prospect field as a parameter. For a list of prospect fields, see Object Field References.

Create a prospect with the email address kmandair@sample.com, the first name Kulvir, and the last name Mandair.

Removes one or more specified prospects. You can specify prospects by Account Engagement ID or email address.

Delete the prospect with Account Engagement ID 58564819.

Requests top-level information about prospects that match the specified criteria. You can specify which prospects and which fields to request. A maximum of 200 prospects are returned, unless you specify the output as mobile. If you specify the output as mobile, then all prospects are returned.

Note: To request detailed information about a specific prospect, use Prospect Read.

To specify which prospects to return, use these parameters. You can use the parameters in any combination and in any order unless otherwise specified.

Notes:

ParameterDatatypeOptionsDescription
assignedbooleantrue, falseIf true, returns prospects that are assigned to a user or a group. If false, returns unassigned prospects. Example: To request all the unassigned prospects, use /api/prospect/version/4/do/query?assigned=false
assigned_to_userinteger or stringany positive integer or any stringRequests the prospects that are assigned to the specified user. If no prospects are assigned to the specified user, returns 0. Use email address or Account Engagement ID to specify users. Note: assigned_to_user overrides assigned. Example: To request all the prospects that are assigned to the user with ID=20700xxx, use /api/prospect/version/4/do/query?assigned_to_user=20700xxx
created_afterstringtoday, yesterday, last_7_days, this_month, last_month,<custom_time>Requests prospects created after the specified time. Example: To request prospects created after midnight on January 1, 2020, use /api/prospect/version/4/do/query?created_after=2020-01-01 00:00:00
created_beforestringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Requests prospects created before the specified date and time. Doesn’t include prospects created on the specified date. <custom_time> Example: to request prospects created before today (but not created today), use api/prospect/version/4/do/query?created_before=today
deletedbooleantrue, falseRequests prospects that were deleted. Default value is false. For more information on recovering deleted prospects, see "Deleting and Undeleting Prospects" in Salesforce Help.
grade_equal_tostringA+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, FRequests prospects that have a grade equal to the specified grade. Example: To request prospects that have a grade equal to B+, use api/prospect/version/4/do/query?grade_greater_than=B+
grade_greater_thanstringA+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, FRequests prospects that have a grade greater than the specified grade.
grade_less_thanstringA+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, FRequests prospects that have a grade less than the specified grade. Parameters must be URL-encoded.
id_greater_thanintegerany positive integerRequests prospects that have an Account Engagement ID greater than the specified number.
id_less_thanintegerany positive integerReturns prospects that have an Account Engagement ID less than the specified number.
is_starredbooleantrue, falseIf true, requests prospects that are starred. If false, requests prospects that aren’t starred.
last_activity_beforestringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Requests prospects with last_activity_at property earlier than the specified time.
last_activity_afterstringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Requests prospects with a last_activity_at later than the specified time.
last_activity_neverbooleantrue,falseRequests prospects with last_activity_at equal to null.
list_idintegerany positive integerRequests prospects that are on the specified email list. Example: To request prospects that are on the dynamic email list with an Account Engagement ID of 1263xx, use api/prospect/version/4/do/query?list_id=1263xx
newbooleantrue, falseRequests prospects that aren’t assigned, don't have is_reviewed equal to true, and have a last_activity_at specified. The new parameter overrides the assigned, assigned_to_user, last_activity_at, and last_activity_before parameters.
score_equal_tointegerany integerRequests prospects with a score equal to the specified number.
score_greater_thanintegerany integerRequests prospects with a score greater than the specified integer.
score_less_thanintegerany integerRequests prospects with a score less than the specified integer.
updated_afterstringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Requests prospects that were last updated after the specified time.
updated_beforestringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Selects prospects that were last updated before the specified time.

Use these parameters to specify which prospect fields are returned, and how the prospects are sorted.

ParameterDatatypeOptionsDescription
fieldsarrayany valid field nameThe fields to return. If unspecified, all fields (including default and custom fields) are returned. Example: To return only the industry, campaign, and company fields, use /api/prospect/version/4/do/query?fields=industry,campaign_id,company
limitintegerany integer from 1 through 200The number of prospects to return. The default value is 200.
offsetintegerany positive integerThe number of prospects to omit from the response (the number to "skip over"). Example: Retrieve a list of prospects, omitting the 50 most recently updated prospects. Sort the query by the updated_at field and use offset=50: api/prospect/version/4/do/query?sort_by=updated_at&offset=50
outputstringsimple, mobileThe format to be used when returning the results of the query. See XML Response.
sort_bystringcreated_at, id, probability, valueThe field by which the results are sorted. See Sort Order.
sort_orderstringascending, descendingThe sort order. The default value depends on which sort_by parameter you specify. See Sort Order.

Use the sort_by parameter to specify which field Account Engagement uses to sort the results. Different fields have different default sort orders. Sort order isn't guaranteed unless specified by the caller. When using offset, it's recommended to sort on a unique identifier - such as ID - to avoid duplicate records.

ValueDefault Sort OrderDescription
created_atdescendingSort the results by the prospects' created_at timestamps.
idascendingSort the results by the prospects' id fields.
last_activity_atdescendingSort the results by the prospects' last_activity_at timestamps.
updated_atdescendingSort the results by the prospects' updated_at timestamps.

Requests detailed information for the specified prospect, including information from the records of related objects. You can specify the prospect by Account Engagement ID, CRM FID, or email address. Returned information includes values from the prospect record along with these values:

  • the Account Engagement ID and name of the Account Engagement campaigns to which the prospect is assigned
  • the prospect profile
  • all visitor activities
  • email list subscriptions
  • information for all custom fields

A prospect can have many visitor activity records. To limit the number of records from related objects that are returned, use limit_related_records. For more information on the XML response, see XML Response for Prospect Read.

Request the information for the prospect with email user1@email.com.

Updates information for the specified prospect. You can specify prospect by Account Engagement ID, CRM FID, or email address. Fields that aren’t specified in the request aren’t changed. To clear a field, submit a parameter with no value.

Returns an updated version of the prospect.

Updating multi-value fields

You can update a multi-value field, such as a checklist, by specifying all the values in the multi-value field. The values that you specify replace all existing values. Use an index to specify the value to update:

<field_name>_<N>=<value>

Where <N> is the zero-based index of the value to update.

Add or remove a prospect to or from an email list

You can add or remove a prospect from an email list using the list ID. To add a prospect to a list:

list_<list_id>=1

To remove a prospect from a list:

list_<list_id>=0.

The following parameters can be used in a prospect update request:

  • Any prospect field name, including custom field names.
  • list_<list_id>=0
  • list_<list_id>=1

To update a prospect's job title to Senior Product Marketing Director, use the parameter-value pair job_title=Product Marketing Director:

Remove the prospect (with Account Engagement ID equal to 10000) from the email list (with email list ID 12345).

Creates a prospect or updates information for the specified prospect. You can specify prospect by Account Engagement ID, CRM FID, or email address. Specifying by email address always creates a prospect. Fields that aren’t specified in the request aren’t changed. To clear a field, submit a parameter with no value. It's efficient to use upsert instead of update in cases where you're not sure whether the prospect exists or not.

Returns an updated version of the prospect.

The following parameters can be used in a prospect upsert request:

  • Any prospect field name, including custom field names.

To update a prospect's job title to Senior Product Marketing Director, use the parameter-value pair job_title=Product Marketing Director:

The XML response for a query request contains top-level information for multiple prospects. The XML response for a read request contains both top-level and detailed information for a single prospect.

Use prospect query to return top-level information for prospects. Use prospect read to return detailed information about a single prospect.

TagDescription
<result>Contains the prospects that match the parameters specified in your query.
<total_results>Contains the number of prospects selected by the query. Note The query request returns a maximum of 200 prospects. If your query matches more than 200 prospects, you can make several requests to retrieve all matching prospects.
<prospect>The information for an individual Prospect. See the Prospect entry in the Object Field Reference for complete descriptions. Note: Information from related objects including the prospect's profile criteria matchings, visitor activities, and list subscriptions aren’t returned. To retrieve that information, use the read request for a specific prospect.

Use prospect read to return detailed information about a single prospect. Use prospect query to return top-level information for a list of prospects. A read response includes the same information as a query response, plus the prospect's profile criteria, visits, visitor activities, and list subscriptions.

The XML response depends on whether you specify output=full, output=simple, or output=mobile. See Description of XML Response Tags for more information about the tags.

XML response for output=full:

The XML response for output=simple:

The XML response for output=mobile:

This response can return more than 200 records.

The XML response contains top-level information, plus information from related records.

TagDescription
<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 on 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, and an <identified_company> and a <visitor_referrer> tag. For complete field listing, see Visitor in Object Field References.
<identified_company>Contains data fields for a visitor's identified company. For a complete list of the fields, 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 the prospect. Contains <visitor_activity> tags only.
<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 <list_subscription> tags only.
<list_membership>Contains data fields for an email list subscription, and a <list> tag. For complete field listing, see Email List Membership in Object Field References.
<list>Contains data fields for a list. For complete field listing, see List in Object Field References.