Version 3 and 4 Overview

The Account Engagement API lets your application access current data within Account Engagement. Through the API, you can perform several common operations on Account Engagement objects including the following:

create – Creates an 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.

You must authenticate using a Salesforce OAuth endpoint. See Authentication for more.

Keep a few considerations in mind 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 or POST
Must pass the access token.
Must pass Account Engagement Business Unit ID in an HTTP Pardot-Business-Unit-Id header (obtained using Salesforce OAuth) to authenticate.
Must use the correct URL for your Account Engagement environment. See Test and Production Environments.

Sample GET Request

These examples use a production environment, so the domain is pi.pardot.com. If you are using a test environment, your domain is pi.demo.pardot.com. See Test and Production Environments.

1GET https://pi.pardot.com/api/<object>/version/3/do/<op>/<id_field>/<id>?<params> HTTP/1.1
2Authorization: Bearer <access_token>
3Pardot-Business-Unit-Id: <pardot_business_unit_id>

Sample POST Request

1POST https://pi.pardot.com/api/<object>/version/3/do/<op>/<id_field>/<id> HTTP/1.1
2Authorization: Bearer <access_token>
3Pardot-Business-Unit-Id: <pardot_business_unit_id>
4
5<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 objects
`access_token`	X	The access token obtained during Authentication
`pardot_business_unit_id`	X	The Account Engagement 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 can 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: Error Codes and Messages

Changing the API Response Format

The Account Engagement 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 Account Engagement object and all objects associated with it.
simple – Returns all supported data for the Account Engagement 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 Account Engagement 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 Account Engagement API because it makes error handling cumbersome.

1<?php
2/**
3 * Class SamplePardotApiClient
4 *
5 * Example PHP client to call the Account Engagement API
6 */
7class SamplePardotApiClient
8{
9    const BASE_URL = "https://pi.pardot.com/api/";
10    const SALESFORCE_OAUTH_TOKEN_URL = "https://login.salesforce.com/services/oauth2/token";
11
12    /** @var int $apiVersion */
13    private int $apiVersion;
14
15    /** @var string $format  */
16    private string $format;
17
18    /**
19     * SamplePardotApiClient constructor.
20     * @param int $apiVersion
21     * @param string $format
22     */
23    public function __construct(int $apiVersion, string $format = 'xml')
24    {
25        $this->apiVersion = $apiVersion;
26        $this->format = $format;
27    }
28
29    /**
30     * @param string $endpoint
31     * @param string $operation
32     * @param array $data
33     * @param array $headers
34     * @param array $queryParams
35     * @return array
36     * @throws Exception
37     */
38    public function post(string $endpoint, string $operation, $data = [], $headers = [], $queryParams = [])
39    {
40        $curl_handle = $this->initRequest($endpoint, $operation, $headers, $queryParams);
41        curl_setopt($curl_handle, CURLOPT_POST, true);
42        // Add POST data if given
43        if (!empty($data)) {
44            curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data);
45        }
46
47        return $this->executeCall($curl_handle);
48    }
49
50    /**
51     * @param string $endpoint
52     * @param string $operation
53     * @param array $headers
54     * @param array $queryParams
55     * @return array
56     * @throws Exception
57     */
58    public function get(string $endpoint, string $operation, $headers = [], $queryParams = [])
59    {
60        $curl_handle = $this->initRequest($endpoint, $operation, $headers, $queryParams);
61
62        return $this->executeCall($curl_handle);
63    }
64
65    /**
66     * @param string $endpoint
67     * @param string $operation
68     * @param array $headers
69     * @param array $queryParams
70     * @return false|resource
71     */
72    private function initRequest(string $endpoint, string $operation, $headers = [], $queryParams = [])
73    {
74        // Construct our full URL to the Account Engagement API
75        $url = $this->buildUrl($endpoint, $operation);
76        // Add desired format to any query string params provided
77        $queryParams['format'] = $this->format;
78        // Build query string params into an encoded string
79        $queryString = http_build_query($queryParams, null);
80        // Append query string params to URL
81        $url .= "?{$queryString}";
82
83        // Init curl handle and set standard curl options: timeouts / require SSL / verify SSL
84        $curl_handle = curl_init($url);
85        curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 5);
86        curl_setopt($curl_handle, CURLOPT_TIMEOUT, 30);
87        curl_setopt($curl_handle, CURLOPT_PROTOCOLS, CURLPROTO_HTTPS);
88        curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, 2);
89        curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, 1);
90
91        // Add any headers passed in such as Authorization header
92        if (!empty($headers)) {
93            curl_setopt($curl_handle, CURLOPT_HTTPHEADER, $headers);
94        }
95
96        return $curl_handle;
97    }
98
99    /**
100     * @param string $endpoint
101     * @param string $operation
102     * @return string
103     */
104    private function buildUrl(string $endpoint, $operation = "")
105    {
106        if ($endpoint === 'login') {
107            return self::SALESFORCE_OAUTH_TOKEN_URL;
108        }
109
110        return self::BASE_URL . "{$endpoint}/version/{$this->apiVersion}/do/{$operation}";
111    }
112
113    /**
114     * @param $curl_handle
115     * @return array
116     * @throws Exception
117     */
118    private function executeCall($curl_handle)
119    {
120        // Execute our call to the Account Engagement API
121        $rsp = curl_exec($curl_handle);
122        // Gather the HTTP response code and last effective URL called
123        $httpCode = curl_getinfo($curl_handle, CURLINFO_HTTP_CODE);
124        $url = curl_getinfo($curl_handle, CURLINFO_EFFECTIVE_URL);
125
126        // Handle errors in calls, this could be a log or an exception thrown as written here
127        if (!$rsp) {
128            $errorMessage = curl_error($curl_handle);
129            curl_close($curl_handle);
130            throw new Exception("Error calling API. HTTP Code: {$httpCode}. Message: {$errorMessage}");
131        }
132        curl_close($curl_handle);
133
134        // Output call response for informational purposes
135        echo("URL: {$url}" . PHP_EOL);
136        echo("HTTP Response Code: {$httpCode}" . PHP_EOL);
137        echo("Response: {$rsp}" . PHP_EOL . PHP_EOL);
138
139        return [$httpCode, $rsp];
140    }
141
142    /**
143     * Use Account Engagement API with a SSO user.
144     * Getting the access token and using that to use the Account Engagement API.
145     */
146    public function executeRequests()
147    {
148        // Setup user credentials
149        $credentials = [
150            "grant_type" => "password",
151            "client_id" => "<your_client_id>",
152            "client_secret" => "<your_client_secert>",
153            "username" => "<your_salesforce_email>",
154            "password" => "<your_password>"
155        ];
156
157        $pardot_business_unit_id = "<Pardot_business_unit_id>";
158
159        // Authenticate to Salesforce - Must be a POST with credentials in the message body
160        list($httpCode, $rsp) = $this->post('login', '', $credentials, null, [], true);
161        // Capture the access_token from a successful login response
162        $access_token = json_decode($rsp, true)['access_token'];
163
164        // Create Authorization Header from access_token and business unit
165        $authHeader = ["Authorization: Bearer {$access_token}", "Pardot-Business-Unit-Id: {$pardot_business_unit_id}"];
166
167        // Call Prospect Query
168        list($httpCode, $rsp) = $this->get('prospect', 'query', $authHeader, ['limit' => 1]);
169        // Call VisitorActivity Query
170        list($httpCode, $rsp) = $this->get('visitorActivity', 'query', $authHeader, ['limit' => 1]);
171        // Create a Campaign
172        list($httpCode, $rsp) = $this->post(
173            'campaign',
174            'create',
175            ['name' => 'A Campaign', 'cost' => 100],
176            $authHeader
177        );
178    }
179}
180
181// Prepare to call version 3 or 4 of the API with JSON or XML responses
182$client = new SamplePardotApiClient(4, 'json');
183
184// Authenticate to Account Engagement - Using Salesforce OAuth
185$client->executeRequests();