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.
Determining when these changes are applicable
As soon your Pardot org is upgraded to allow multiple prospects with the same email address, your current API session will be cleared and you must log in again. Upon logging in, a new field will be returned in the login response. This will be your indication that you may no longer use version 3 (or any other previous version), and must now use the version 4 syntax. Here's what that will look like:
POST: https://pi.pardot.com/api/login/version/3 message body: email=<email>&password=<password>&user_key=<user_key>
Response (Before transition):
<rsp stat="ok" version="1.0"> <api_key>1234abcd</api_key> </rsp>
Response (After transition):
<rsp stat="ok" version="1.0"> <api_key>5678qwertyuiop</api_key> <version>4</version> </rsp>
Note: Using version 3 to login will continue to work, even though all other endpoints will require version 4
Request Path Changes
You will need to modify your request to use the
/version/4 path. For example:
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
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 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
- Read: When making a read query, querying by
fidwill only return the one matching prospect.
- Update: Prospects can no longer be updated when referenced via
- Upsert: Upsert query by
fidwill update or create as needed. See Upserting Prospects for more details.
- Delete: Delete query must reference by Pardot
- Batch processing: Examples of batch processing can be found here
Opportunity API changes
- 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 will be used. If you want to apply the opportunity to a specific prospect, then you must reference the prospect using
- Query: If you query using a
prospect_emailreference, you will receive opportunities that correspond with any prospects that share that email address. if you want a specific prospect then query by the
Visitor API changes
- Assign: Assigning by
prospect_id) will return an error.