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:
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
fidfield 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.
- Create: Prospects can still be created with a referenced
- Read: When making a read query, querying by
fidonly 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
- Upsert: Upsert query by
fidupdates or creates as needed. See Upserting Prospects for more details.
- Delete: Delete query must reference by Account Engagement
- Batch processing: See examples of batch processing in the Prospect object documentation.
See the Prospect object documentation.
- Create: Creating an opportunity using a
prospect_emailreference 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
- Query: If you query using a
prospect_emailreference, you receive opportunities that correspond with any prospects that share that email address. if you want a specific prospect then query by the
See the Opportunity Object documentation.
- Assign: Assigning by
prospect_id) returns an error.
See the Visitor Object documentation.