Version 5 (Beta) Overview

As a beta feature, v5 of the Pardot API is a preview and isn’t part of the “Services” under your master subscription agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. This feature is for evaluation purposes only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature. You can provide feedback and suggestions for v5 of the Pardot API in this Google Form.

Functionality in Version 5 (Beta)

You can use version 5 (beta) of the Pardot API to access Pardot's File and Layout Template objects. Version 5 (beta) also allows for read access to a subset of fields on Campaign, Tracker Domain, and User objects. For information about other objects, see the documentation for versions 3 or 4 .

Authentication

Developers must authenticate using a Salesforce OAuth endpoint or the Pardot API login endpoint before issuing Pardot API requests. For more information, see Authentication. Examples below are shown using Salesforce OAuth Access Tokens, but Pardot API Keys may be used as well.

Formatting Object API Requests

Use one of the following HTTP verbs for your version 5 (beta) API requests:

Read (using GET)

Read requests are formatted as follows:

GET /api/v5/objects/<object-collection>/<id>?<params> HTTP/1.1
Host: pi.pardot.com
Authorization: Bearer <access-token>

Parameters

Parameter Required Description
fields X A comma delimited list of fields to return. Use dot-delimited notation (<field-name>.<sub-object-field-name>) to specify fields on sub-objects.
deleted (Defaults to false). Specify true to return an object regardless of whether it is in the recycle bin or not. Specify false to indicate that an error should be returned for deleted objects in the recycle bin (not distinguishing them from permanently deleted objects). (Only supported for objects which are moved to the recycle bin in Pardot when deleted.)

Optional Header

A request may include an If-Modified-Since header with an RFC7231 formatted date and time to check against the last updated time of the requested object.

Response

Responses include, but are not limited to:

Status Error Code Notes
200 OK The response body will contain fields for the object as documented in Response Format. A Last-Modified header will be included on the response (see Response Headers).
304 Not Modified The object has not been updated since the time specified in an included If-Modified-Since request header. The response body will be empty.

Create (using POST)

Create requests are formatted as follows:

POST /api/v5/objects/<object-collection>?<params> HTTP/1.1
Host: pi.pardot.com
Authorization: Bearer <access-token>
Content-Type: <content-type>

<input-representation> or <multi-part-request-body>

Unless sending a file as part of the request (see below), the content type must be application-json.

Parameters

Parameter Required Description
fields (Defaults to "id".) A comma delimited list of fields to return for the newly created object. Use dot-delimited notation (<field-name>.<sub-object-field-name>) to specify fields on sub-objects.

Multipart Request Bodies

Some objects (such as File) require a file to be uploaded along with the input representation when creating the object. In these cases the header Content-Type: multipart/form-data must be specified and the post data must have the following named parts:

Input representation

When creating an object a JSON formatted input representation must be included to specify fields for the object.

{
  "<field-name>": <value>,
  ...
}

Response

Responses include, but are not limited to:

Status Error Code Notes
201 Created The object was successfully created. The response body will contain fields for the object as documented in Response Format. The response will also contain a Location header with the URL to read the object (including the same fields requested in the fields parameter.

Update (using PATCH)

Update requests are formatted as follows:

PATCH /api/v5/objects/<object-collection>/<id>?<params> HTTP/1.1
Host: pi.pardot.com
Authorization: Bearer <access-token>
Content-Type: <content-type>

<input-representation> or <multi-part-request-body>

Unless sending a file as part of the request (see below), the content type must be application-json.

Parameters

Parameter Required Description
fields (Defaults to no fields.) A comma delimited list of fields to return for the updated object. Use dot-delimited notation (<field-name>.<sub-object-field-name>) to specify fields on sub-objects.

Multipart Request Bodies

Some objects (such as File) allow a file to be uploaded along with the input representation when creating the object. When uploading a file these cases the header Content-Type: multipart/form-data must be specified and the post data must have one or more of the following named parts:

If the update only includes fields and not a file, a multipart request body is not needed. This is true even for objects that require a file (and thus a multipart request body) at creation time.

Input representation

When updating an object a JSON formatted input representation must be included to specify fields for the object.

{
  "<field-name>": <value>,
  ...
}

Fields that are omitted will be left unchanged.

Response

Responses include, but are not limited to:

Status Error Code Notes
200 OK The object was successfully updated. The response body will contain fields for the object as documented in Response Format.
204 No Content The object was successfully updated. Because no output fields were requested, the response body will be empty.

Delete (using DELETE):

For some object types, delete requests result in permanent deletion. For other object types, delete requests move the object to the Pardot recycle bin.

Delete requests do not cause related objects to be deleted.

Delete requests are formatted as follows:

DELETE /api/v5/objects/<object-collection>/<id> HTTP/1.1
Host: pi.pardot.com
Authorization: Bearer <access-token>

Response

Responses include, but are not limited to:

Status Error Code Notes
204 No Content Object was successfully deleted. The response body is empty.
405 Method Not Allowed 108 Object could not be deleted because it is used in other places.

Response Format

Version 5 (beta) responses are formatted as JSON unless otherwise noted.

{
  "<field-name>": value,
  ...
  "<field-name>": {
    "<field-name>": value,
    ...
  }
}

As shown above, fields that are references to other objects have a JSON object with fields of the referenced object as their values. These are requested using dot delimited notation in the fields URL parameter.

Response headers:

Header                    Description
Last-Modified Date that the object was last modified. (Sent only for GET requests.)
Pardot-Warning Included in certain circumstances. Example: Pardot-Warning:201;Record In Recycle Bin when an API call fails because an object has been deleted and is in the recycle bin.

Pardot-Warning header values

Value Description
201;Record In Recycle Bin The API call failed because an object has been deleted and is in the recycle bin.
202;Record(s) have been redacted from output due to access rules Some values have been omitted from the API response because the user making the call does not have sufficient access rights to see the omitted data.

Data Types

Fields may be of the following data types:

Type Notes
String String of characters.
Integer Number that must not contain a decimal point.
Boolean The value true or false.
DateTime ISO 8601 formatted date and time (including timezone offset).
Object Some fields are references to another object. In these cases, responses can contain fields of the referenced object. Note that these are generally read only fields. Data will be a JSON object containing fields that were specified in the fields parameter using dot delimited notation.

Error Responses

Error responses from version 5 (beta) of the Pardot API have 4xx or 5xx HTTP status codes.

Response statuses include, but are not limited to:

Status Notes
400 Bad Request Possible reasons include missing required parameters.
404 Not Found Object with the given ID does not exist or is in the recycle bin.
405 Method Not Allowed The operation cannot be performed because the user has insufficient access rights, or a condition exists that prevents the operation from being performed.

The response body will contain an error code and a more detailed message. (Error codes are listed in Error Codes & Messages).

{
  "code": <error_code>,
  "message": <error_message>
}