What Is Version 4?

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

To determine if your Pardot org has AMPSEA enabled, check out this guide.

Transitioning from Version 3 to Version 4

If you want to enable AMPSEA in your Pardot account, use the following guidelines to keep using Pardot APIs.

Request Path Changes

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

Before:

GET: https://pi.pardot.com/api/prospect/version/3/read/id/1

After:

GET: https://pi.pardot.com/api/prospect/version/4/read/id/1

Prospect API Changes

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.
• 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 Pardot 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 Pardot id or Salesforce fid references.
• Upsert: Upsert query by email always creates a prospect. Upsert by Pardot id or Salesforce fid updates or creates as needed. See Upserting Prospects for more details.
• Delete: Delete query must reference by Pardot id or Salesforce fid.
• Batch processing: See examples of batch processing in the Prospect object documentation.

See the Prospect object documentation.

Opportunity API Changes

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

Visitor API Changes

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

See the Visitor Object documentation.