Transitioned from Version 3 to Version 4?

Version 4 was created to accommodate multiple prospects with the same email address. If your Account Engagement business unit has the allow multiple prospects with the same email address (AMPSEA) feature enabled, then use version 4. If your Account Engagement business unit doesn’t have AMPSEA enabled, use version 3.

To determine if your Account Engagement business unit has AMPSEA enabled, check out this guide.

If you want to enable AMPSEA in your Account Engagement business unit, use the following guidelines to keep using Account Engagement APIs.

Update your requests to use the /version/4 path. For example:

Before:

After:

Most of the differences between version 3 and version 4 are in the prospect APIs.

  • New reference field: Prospects can be referenced using the Salesforce CRM Identifier, the fid field. This fid field refers to the ID of the Lead or Contact record in Salesforce. You can find the lead ID (begins with 00Q) or the contact ID (begins with 003) in the URL when viewing a lead or contact record. Or, you can get multiple contacts or lead ID from Salesforce using the export tool. lead_identifier_example
  • Create: Prospects can still be created with a referenced email address. If you call the create API with the same email address multiple times, each call creates a prospect. Previously, you would get an error.
  • Read: When making a read query, querying by email returns all prospects that share that email address. Querying by Account Engagement id or Salesforce fid only returns the one matching prospect.
  • Update: Because there can be multiple prospects with the same email address, prospects can no longer be updated when referenced via email alone. Instead, use either the Account Engagement id or Salesforce fid references.
  • Upsert: Upsert query by email always creates a prospect. Upsert by Account Engagement id or Salesforce fid updates or creates as needed. See Upserting Prospects for more details.
  • Delete: Delete query must reference by Account Engagement id or Salesforce fid.
  • Batch processing: See examples of batch processing in the Prospect object documentation.

See the Prospect object documentation.

  • Create: Creating an opportunity using a prospect_email reference must correspond to an existing prospect. If there are multiple prospects with that email address, the prospect with the most recent activity date is used. If you want to apply the opportunity to a specific prospect, then reference the prospect using prospect_id.
  • Query: If you query using a prospect_email reference, you receive opportunities that correspond with any prospects that share that email address. if you want a specific prospect then query by the prospect_id.

See the Opportunity Object documentation.

  • Assign: Assigning by prospect_email alone (no prospect_id) returns an error.

See the Visitor Object documentation.