Prospect Object

Learn more about prospects in Salesforce Help.

Search criteria may be used together in any combination and/or order unless otherwise specified. Unless output=mobileis specified, 200 prospects will be returned with each query request. This limit is not enforced for responses formatted for mobile devices.

Since query result sets are limited to 200 results each, the results returned may not include all prospects that were matched by the query. To retrieve the remaining results, the following criteria can be used to navigate through the result set.

The ordering of the results returned by a query request can be changed by specifying sort_by and sort_order parameters. Any of the following values are valid when specifying the sort_by parameter. For a complete list of fields involved in Prospect queries, see Prospect in Object Field References.

For a complete list of fields involved in Prospect operations, see the Prospect section of Object Field References.

For output=full:

For output=simple:

For output=mobile:

To assign/reassign a prospect, both the prospect to be assigned and the target user or group of the assignment must be defined. Prospects can be specified by their Account Engagement ID or email address. Users or groups can be specified by their Account Engagement user ID, email address, or Account Engagement group ID. Possible combinations of parameters are shown below. Developers are responsible for substituting specific values for parameters denoted by <carets>.

Examples:

/api/prospect/version/3/do/assign/email/?user_email=

/api/prospect/version/3/do/assign/email/?user_id=

/api/prospect/version/3/do/assign/email/?group_id=

/api/prospect/version/3/do/assign/id/?user_email=

/api/prospect/version/3/do/assign/id/?user_id=

/api/prospect/version/3/do/assign/id/?group_id=

XML responses to assign requests are identical to read requests, but reflect the new prospect assignment in the <assigned_to> node.

To create a prospect via the API, only a valid and unique email address is required. Values for any other prospect fields may also be provided in the create request. Developers are responsible for substituting specific values for parameters denoted by <carets>.

Example: Creating a new prospect/api/prospect/version/3/do/create/email/new_prospect@company.com?first_name=New&last_name=Prospect

XML responses to create requests are identical to update and read requests. If no campaign_id value is provided, the new prospect will be automatically assigned to the oldest existing campaign.

There are 3 endpoints available for batch processing up to 50 prospects at a time:

/api/prospect/version/3/do/batchCreate

/api/prospect/version/3/do/batchUpdate

/api/prospect/version/3/do/batchUpsert

These endpoints expect a query variable called "prospects" which holds either JSON or XML encoded data. Each prospect should have a unique identifier which will be used in the return output.

JSON Example:

XML Example:

If using batchCreate, you'll need to provide a valid and unique email address for each prospect. The batchUpdate and batchUpsert endpoints allow the use of a prospect ID or prospect email address.

Example:

/api/prospect/version/3/do/batchUpdate?prospects={"prospects":{"some@email.com":{"first_name":"New first name","last_name":"New last name"},"1234":{"first_name":"New first name","last_name":"New last name"}}}

Modifying values of prospect data fields is done by submitting an update request with parameters for each field to be updated. Each parameter is formatted as <field_name>=<value>. Custom field values are updated using the same syntax.

Example: Updating the phone number of a prospect whose email address is bob@company.com: /api/prospect/version/3/do/update/email/bob@company.com?phone=888-123-4567

Only values that are specifically named in the request are updated. All others are left unchanged. To clear a value, submit an update request containing a parameter with no specified value, such as phone=.

Modifying values of prospect data fields with predefined values is accomplished through an update request with parameters for each field to be updated. Each parameter is formatted as <field_name>=<value> where <value> matches the predefined field value. Custom field values are updated using the same syntax.

Example: Updating the category of a prospect whose email address is bob@company.com *to the category consumer: /api/prospect/version/3/do/update/email/bob@company.com?category=consumer

Updating field values with multiple values follows the same convention as fields with predefined values, but requires a different parameter naming scheme to allow multiplicity. An update request is submitted with parameters formatted as <field_name>_<count>=<field_value> where <count> is an integer denoting the current parameter's place in sequence. <count> must start at 0 and increase by 1 until all desired values are submitted.

Example: Modifying the values of a custom field with field name past_jobs for a prospect with a Account Engagement ID of 5: /api/prospect/version/3/do/update/id/5?past_jobs_0=janitor&past_jobs_1=security

To modify email list subscriptions for a prospect, the Account Engagement ID of the email list is required. Once the ID is obtained, an update is submitted with parameters formatted as list_<list_id>=1 to create a subscription and list_<list_id>=0 to end a subscription.

Example: Adding a prospect whose email address is bob@company.com to an email list with Account Engagement ID 8: /api/prospect/version/3/do/update/email/bob@company.com?list_8=1

Requests that attempt to subscribe a prospect to lists that it is already subscribed to are ignored. Unsubscribe requests are handled similarly.

To modify a prospect's matching status for associated profile criteria, the Account Engagement ID of the profile criteria is required. Once the ID is obtained, an update is submitted with parameters formatted as profile_criteria_<profile_criteria_id>=<status>. The value of <status> may be either match, nomatch, or unknown.

Example: Setting a profile criteria for a prospect whose email address is bob@company.com to match: /api/prospect/version/3/do/update/email/bob@company.com?profile_criteria_8=match

Example: Setting a profile criteria for a prospect with Account Engagement ID 58 to nomatch: /api/prospect/version/3/do/update/id/58?profile_criteria_8=nomatch

Only profile criteria that belong to the profile associated with the prospect can be updated using this method. Requests to update profile criteria not associated with the assigned profile will be ignored. Using any matching status values other than match, nomatch, or unknown will result in an error message. See Error Codes & Messages for details.

To modify a prospect's matching status for associated prospect account, the Account Engagement ID of the prospect account is required. Once the ID is obtained, an update is submitted with parameters formatted as prospect_account_id=<id>.

Example: Setting a prospect account for a prospect whose email address is bob@company.com to match: /api/prospect/version/3/do/update/email/bob@company.com?prospect_account_id=

A prospect account with the id must exist, and can not be set if a CRM connector is set up in the account.