Version 3 and 4 Overview
Using the API
The Pardot API lets your application access current data within Pardot. Through the API, you can perform several common operations on Pardot objects including the following:
create
-- Creates a new object with the specified parameters.read
-- Retrieves information about the specified object.query
-- Retrieves objects that match specified criteria.update
-- Updates elements of an existing object.upsert
-- Updates elements of an existing object if it exists. If the object does not exist, one is created using the supplied parameters.
Developers must authenticate using a Salesforce OAuth endpoint or the Pardot API login endpoint before issuing Pardot API requests. Refer to the Authentication section for details about this procedure.
Keep in mind a few considerations when you perform requests. For update
requests, only the fields specified in the request are updated. All others are left unchanged. If a required field is cleared during an update
, the request is declined.
Request Format
All requests to the API:
- Must use either HTTP
GET
orPOST
- Must pass access token or user key and api key in an HTTP
Authorization
header. - Must pass Pardot Business Unit ID in an HTTP
Pardot-Business-Unit-Id
header if using an access token (obtained using Salesforce OAuth) to authenticate. - Must use the correct URL for your Pardot environment. See Test and Production Environments.
Sample GET Request
These examples use a production environment, so the domain is pi.demo.pardot.com
. If you are using
a test environment, your domain is pi.demo.pardot.com
. See Test and Production Environments.
With User Key and API Key (obtained through Pardot API login endpoint)
GET https://pi.pardot.com/api/<object>/version/3/do/<op>/<id_field>/<id>?<params> HTTP/1.1
Authorization: Pardot api_key=<your_api_key>, user_key=<your_user_key>
With Salesforce OAuth Access Token (obtained through Salesforce OAuth endpoint)
GET https://pi.pardot.com/api/<object>/version/3/do/<op>/<id_field>/<id>?<params> HTTP/1.1
Authorization: Bearer <access_token>
Pardot-Business-Unit-Id: <pardot_business_unit_id>
Sample POST Request
With User Key and API Key
POST https://pi.pardot.com/api/<object>/version/3/do/<op>/<id_field>/<id> HTTP/1.1
Authorization: Pardot api_key=<your_api_key>, user_key=<your_user_key>
<params>
Request Parameters
Parameter | Required | Description |
---|---|---|
object |
X | The object type to be returned by the API request |
op |
X | The operation to be performed on the specified object type |
id_field |
X | The field to be used as the identifier for the specified object |
id |
X | The identifier for the specified object(s) |
your_api_key |
X | The API key obtained during Authentication |
your_user_key |
X | The user key used during Authentication |
format |
The API data format: either xml (default) or json | |
params |
Parameters specific to your request; See individual methods for details |
With Salesforce OAuth
POST https://pi.pardot.com/api/<object>/version/3/do/<op>/<id_field>/<id> HTTP/1.1
Authorization: Bearer <access_token>
Pardot-Business-Unit-Id: <pardot_business_unit_id>
<params>
Request Parameters
Parameter | Required | Description |
---|---|---|
object |
X | The object type to be returned by the API request |
op |
X | The operation to be performed on the specified object type |
id_field |
X | The field to be used as the identifier for the specified object |
id |
X | The identifier for the specified object(s) |
access_token |
X | The access token obtained during Authentication |
pardot_business_unit_id |
X | The pardot business unit. For details see Authentication |
format |
The API data format: either xml (default) or json | |
params |
Parameters specific to your request; See individual methods for details |
The ordering of parameters is arbitrary. Parameters are passed using conventional HTML parameter syntax, with '?'
indicating the start of the parameter string (for GET requests only) and '&'
as the separator between parameters. With the exception of <format>
and <params>
, all components are required. Data returned from the API is formatted using JSON or XML 1.0 with UTF-8 character encoding. Keep in mind that some characters in the response may be encoded as HTML entities, requiring client-side decoding. Also, keep in mind that all parameters specified in an API request MUST be URL-encoded before they are submitted.
In general, the API returns XML or JSON containing a current version of the target object's data. But unsuccessful requests return a short response containing an error code and message. See Error Codes & Messages for error descriptions and suggested remedies: kb/error-codes-messages
Changing the API Response Format
The Pardot API supports several output formats, and each returns different levels of detail in the XML or JSON response. Output formats are defined by specifying the output
request parameter. Supported output formats include:
full
-- Returns all supported data for the Pardot object and all objects associated with it.simple
-- Returns all supported data for the data for the Pardot object.mobile
-- Returns an abbreviated version of the object data. This output format is ideal for mobile applications.bulk
-- Returns basic data for an object (does not provide total object count). Used for querying large amounts of data.
If the output request parameter is not defined, the output format defaults to full
. See the XML Response Format sections for each object for details about the formats.
Sample Code
Here's an example of calling the Pardot API using a simple PHP client using the cURL library.
Note: We strongly recommend against using PHP's file_get_contents
function to call the Pardot API because
it makes error handling extremely cumbersome.
<?php
/**
* Class SamplePardotApiClient
*
* Example PHP client to call the Pardot API
*/
class SamplePardotApiClient
{
const BASE_URL = "https://pi.pardot.com/api/";
const SALESFORCE_OAUTH_TOKEN_URL = "https://login.salesforce.com/services/oauth2/token";
/** @var int $apiVersion */
private $apiVersion;
/** @var string $format */
private $format;
public function __construct($apiVersion, $format = 'xml')
{
$this->apiVersion = $apiVersion;
$this->format = $format;
}
/**
* @param string $endpoint
* @param string $operation
* @param array $data
* @param array $headers
* @param array $queryParams
* @param bool $useSalesforceOAuth
* @return array
* @throws Exception
*/
public function post($endpoint, $operation, $data = [], $headers = [], $queryParams = [], $useSalesforceOAuth = true)
{
$curl_handle = $this->initRequest($endpoint, $operation, $headers, $queryParams, $useSalesforceOAuth);
curl_setopt($curl_handle, CURLOPT_POST, true);
// Add POST data if given
if (!empty($data)) {
curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
}
return $this->executeCall($curl_handle);
}
/**
* @param string $endpoint
* @param string $operation
* @param array $headers
* @param array $queryParams
* @param bool $useSalesforceOAuth
* @return array
* @throws Exception
*/
public function get($endpoint, $operation, $headers = [], $queryParams = [], $useSalesforceOAuth = true)
{
$curl_handle = $this->initRequest($endpoint, $operation, $headers, $queryParams, $useSalesforceOAuth);
return $this->executeCall($curl_handle);
}
/**
* @param string $endpoint
* @param string $operation
* @param array $headers
* @param array $queryParams
* @param bool $useSalesforceOAuth
* @return false|resource
*/
private function initRequest($endpoint, $operation, $headers = [], $queryParams = [], $useSalesforceOAuth = true)
{
// Construct our full URL to the Pardot API
$url = $this->buildUrl($endpoint, $operation, $useSalesforceOAuth);
// Add desired format to any query string params provided
$queryParams['format'] = $this->format;
// Build query string params into an encoded string
$queryString = http_build_query($queryParams, null, '&');
// Append query string params to URL
$url .= "?{$queryString}";
// Init curl handle and set standard curl options: timeouts / require SSL / verify SSL
$curl_handle = curl_init($url);
curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($curl_handle, CURLOPT_TIMEOUT, 30);
curl_setopt($curl_handle, CURLOPT_PROTOCOLS, CURLPROTO_HTTPS);
curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, 1);
// Add any headers passed in such as Authorization header
if (!empty($headers)) {
curl_setopt($curl_handle, CURLOPT_HTTPHEADER, $headers);
}
return $curl_handle;
}
/**
* @param string $endpoint
* @param string $operation
* @param bool $useSalesforceOAuth
* @return string
*/
private function buildUrl($endpoint, $operation = "", $useSalesforceOAuth = true)
{
if ($endpoint === 'login') {
if ($useSalesforceOAuth) {
return self::SALESFORCE_OAUTH_TOKEN_URL;
} else {
return self::BASE_URL . "login";
}
}
return self::BASE_URL . "{$endpoint}/version/{$this->apiVersion}/do/{$operation}";
}
/**
* @param $curl_handle
* @return array
* @throws Exception
*/
private function executeCall($curl_handle)
{
// Execute our call to the Pardot API
$rsp = curl_exec($curl_handle);
// Gather the HTTP response code and last effective URL called
$httpCode = curl_getinfo($curl_handle, CURLINFO_HTTP_CODE);
$url = curl_getinfo($curl_handle, CURLINFO_EFFECTIVE_URL);
// Handle errors in calls, this could be a log or an exception thrown as written here
if (!$rsp) {
$errorMessage = curl_error($curl_handle);
curl_close($curl_handle);
throw new Exception("Error calling API. HTTP Code: {$httpCode}. Message: {$errorMessage}");
}
curl_close($curl_handle);
// Output call response for informational purposes
echo("URL: {$url}" . PHP_EOL);
echo("HTTP Response Code: {$httpCode}" . PHP_EOL);
echo("Response: {$rsp}" . PHP_EOL . PHP_EOL);
return [$httpCode, $rsp];
}
/**
* Use Pardot API using Api Key and User Key.
*/
public function executeRequestsWithApiKeys()
{
// Setup user credentials
$credentials = [
'user_key' => '<your_user_key>',
'email' => '<your_pardot_user_email>',
'password' => '<your_password>'
];
// Authenticate to Pardot - Must be a POST with credentials in the message body
list($httpCode, $rsp) = $this->post('login', '', $credentials, null, [], false);
// Capture the api_key from a successful login response
// api_key is good for 1 hour and can be reused on subsequent calls
$apiKey = json_decode($rsp, true)['api_key'];
// Create Authorization Header from api_key
$authHeader = ["Authorization: Pardot user_key={$credentials['user_key']},api_key={$apiKey}"];
// Call Prospect Query
list($httpCode, $rsp) = $this->get('prospect', 'query', $authHeader, ['limit' => 1]);
// Call VisitorActivity Query
list($httpCode, $rsp) = $this->get('visitorActivity', 'query', $authHeader, ['limit' => 1]);
// Create a Campaign
list($httpCode, $rsp) = $this->post(
'campaign',
'create',
['name' => 'A Campaign', 'cost' => 100],
$authHeader
);
}
/**
* Use Pardot API with a SSO user.
* Getting the access token and using that to use the Pardot API.
*/
public function executeRequestsWithSalesforceOAuth()
{
// Setup user credentials
$credentials = [
"grant_type" => "password",
"client_id" => "<your_client_id>",
"client_secret" => "<your_client_secert>",
"username" => "<your_salesforce_email>",
"password" => "<your_password>"
];
$pardot_business_unit_id = "<Pardot_business_unit_id>";
// Authenticate to Salesforce - Must be a POST with credentials in the message body
list($httpCode, $rsp) = $this->post('login', '', $credentials, null, [], true);
// Capture the access_token from a successful login response
$access_token = json_decode($rsp, true)['access_token'];
// Create Authorization Header from access_token and business unit
$authHeader = ["Authorization: Bearer {$access_token}", "Pardot-Business-Unit-Id: {$pardot_business_unit_id}"];
// Call Prospect Query
list($httpCode, $rsp) = $this->get('prospect', 'query', $authHeader, ['limit' => 1]);
// Call VisitorActivity Query
list($httpCode, $rsp) = $this->get('visitorActivity', 'query', $authHeader, ['limit' => 1]);
// Create a Campaign
list($httpCode, $rsp) = $this->post(
'campaign',
'create',
['name' => 'A Campaign', 'cost' => 100],
$authHeader
);
}
}
// Prepare to call version 3 or 4 of the API with JSON or XML responses
$client = new SamplePardotApiClient(4, 'json');
// Authenticate to Pardot - Using API Keys
$client->executeRequestsWithApiKeys();
// Authenticate to Pardot - Using Salesforce OAuth
$client->executeRequestsWithSalesforceOAuth();