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 Name | Operation | Description |
|---|---|---|
| Prospect Assign | POST | Assign or reassign the specified prospect to an Account Engagement user or group. |
| Prospect Batch Create | POST | Create up to 50 prospects. |
| Prospect Batch Update | POST | Update the specified prospects with the information provided. |
| Prospect Batch Upsert | POST | Update and create prospects with the provided information. |
| Prospect Create | POST | Create a prospect record using an email address. |
| Prospect Delete | DELETE | Delete the specified prospect. |
| Prospect Query | GET | Request information for the prospects that match the specified criteria. |
| Prospect Read | GET | Request detailed information for a single prospect. |
| Prospect Update | POST | Update a prospect's information, including prospect fields, list subscription, and custom fields. |
| Prospect Upsert | POST | Update and create a prospect with the information provided. |
| Prospect Unassign | POST | Unassigns 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.
| Parameter | Type | Description |
|---|---|---|
user_email | string | The user or group's email address. |
user_id | string | The user's ID. |
group_id | string | The 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.
| Parameter | Type | Description |
|---|---|---|
fid | string | The prospect's CRM FID. |
id | string | The 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.
| Parameter | Type | Possible Values | Description |
|---|---|---|---|
| format | string | JSON - 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:
- Parameters must be URL-encoded.
- Dates and times must use GNU Date Input Syntax, for example yyyy-mm-dd:hh:ss
. - For a full listing of prospect fields see Object Field References.
| Parameter | Datatype | Options | Description |
|---|---|---|---|
assigned | boolean | true, false | If 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_user | integer or string | any positive integer or any string | Requests 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_after | string | today, 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_before | string | today, 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 |
deleted | boolean | true, false | Requests 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_to | string | A+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, F | Requests 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_than | string | A+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, F | Requests prospects that have a grade greater than the specified grade. |
grade_less_than | string | A+, A, A-, B+, B, B-, C+, C, C-, D+, D, D-, F | Requests prospects that have a grade less than the specified grade. Parameters must be URL-encoded. |
id_greater_than | integer | any positive integer | Requests prospects that have an Account Engagement ID greater than the specified number. |
id_less_than | integer | any positive integer | Returns prospects that have an Account Engagement ID less than the specified number. |
is_starred | boolean | true, false | If true, requests prospects that are starred. If false, requests prospects that aren’t starred. |
last_activity_before | string | today, yesterday, last_7_days, this_month, last_month, <custom_time> | Requests prospects with last_activity_at property earlier than the specified time. |
last_activity_after | string | today, yesterday, last_7_days, this_month, last_month, <custom_time> | Requests prospects with a last_activity_at later than the specified time. |
last_activity_never | boolean | true,false | Requests prospects with last_activity_at equal to null. |
list_id | integer | any positive integer | Requests 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 |
new | boolean | true, false | Requests 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_to | integer | any integer | Requests prospects with a score equal to the specified number. |
score_greater_than | integer | any integer | Requests prospects with a score greater than the specified integer. |
score_less_than | integer | any integer | Requests prospects with a score less than the specified integer. |
updated_after | string | today, yesterday, last_7_days, this_month, last_month, <custom_time> | Requests prospects that were last updated after the specified time. |
updated_before | string | today, 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.
| Parameter | Datatype | Options | Description |
|---|---|---|---|
fields | array | any valid field name | The 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 |
limit | integer | any integer from 1 through 200 | The number of prospects to return. The default value is 200. |
offset | integer | any positive integer | The 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 |
output | string | simple, mobile | The format to be used when returning the results of the query. See XML Response. |
sort_by | string | created_at, id, probability, value | The field by which the results are sorted. See Sort Order. |
sort_order | string | ascending, descending | The 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.
| Value | Default Sort Order | Description |
|---|---|---|
created_at | descending | Sort the results by the prospects' created_at timestamps. |
id | ascending | Sort the results by the prospects' id fields. |
last_activity_at | descending | Sort the results by the prospects' last_activity_at timestamps. |
updated_at | descending | Sort 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>=0list_<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.
| Tag | Description |
|---|---|
<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.
| 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 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. |