What is Version 4?
In order to accommodate multiple prospects with the same email address, we have created a new version of our APIs - version 4. If your Pardot org has this feature enabled now, then you must use version 4. If your Pardot org does not have this featured enabled, you must use version 3.
To determine if your Pardot org has this feature enabled, check out this guide.
For more information on the API in general, check out the Overview Page.
For specific API endpoints, please select from the "Version 4" list above.
Transitioning from version 3 to version 4
If you are going to upgrade your Pardot org to allow multiple prospects with the same email address, and you use the api, you will need to follow the guidelines below.
Request Path Changes
You will need to modify your request to use the /version/4
path. For example:
Before transition:
GET: https://pi.pardot.com/api/prospect/version/3/read/id/1
After transition:
GET: https://pi.pardot.com/api/prospect/version/4/read/id/1
Prospect API changes
Most of the changes in version 4 occur around the prospect APIs. When you begin using the version 4 APIs, your logic should know about these changes (full documentation can be found here)
- New reference field: Prospects can now be referenced using the Salesforce CRM Identifier, known to the api as the
fid
field. Thisfid
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 as seen below. Or, you can get multiple contacts or lead ids 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 will create a new prospect. Previously, you would get an error. - Read: When making a read query, querying by
email
will return all prospects that share that email address. Querying by Pardotid
or Salesforcefid
will only return the one matching prospect. - Update: Prospects can no longer be updated when referenced via
email
alone. This is because there may now be multiple prospects with the same email address. Instead, you must use either the Pardotid
or Salesforcefid
references. - Upsert: Upsert query by
email
will always create a new prospect. Upsert by Pardotid
or Salesforcefid
will update or create as needed. See Upserting Prospects for more details. - Delete: Delete query must reference by Pardot
id
or Salesforcefid
. - Batch processing: Examples of batch processing can be found here
Opportunity API changes
Full documentation can be found here.
- 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 will be used. If you want to apply the opportunity to a specific prospect, then you must reference the prospect usingprospect_id
. - Query: If you query using a
prospect_email
reference, you will receive opportunities that correspond with any prospects that share that email address. if you want a specific prospect then query by theprospect_id
.
Visitor API changes
Full documentation can be found here.
- Assign: Assigning by
prospect_email
alone (noprospect_id
) will return an error.