Version 5

Functionality in Version 5

You can use version 5 of the Pardot API to read and update a variety of assets and objects, like File and Layout Template objects. For information about other objects that aren't available in version 5, see the documentation for versions 3 or 4.

Data returned by version 5 endpoints isn’t real time, so creates and updates can be delayed when reading and querying data.

Authentication

Developers must authenticate using a Salesforce OAuth endpoint before issuing Pardot API requests. For more information, see Authentication.

Formatting Object API Requests

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

  • GET - on collection endpoint to query for objects.
  • GET - read an object.
  • POST - create an object.
  • PATCH - update an object.
  • DELETE - delete an object.

Query (Using GET)

Query requests are formatted as follows:

Parameters

These parameters are shared across all objects. The object reference defines the parameters specific to the object.

ParameterRequiredDescription
fieldsXA comma delimited list of fields to return. Use dot-delimited notation (<field-name>.<sub-object-field-name>) to specify fields on sub-objects.
deletedSpecify "all" to return records regardless of whether they are in the recycle bin or not. Specify true to return only deleted objects in the recycle bin. Specify false to return objects not found in the recycle bin. (Only supported for objects which are moved to the recycle bin in Pardot when deleted.) Defaults to false.
limitThe number of items to return. This must be a positive integer up to 1000. Defaults to 200.
offsetDeprecated. The index of the first record to return. This must be a positive integer up 2000. If an offset more than 2000 is required, use the Export API instead. Defaults to 0.
orderByA comma delimited list of fields used to sort the results. An optional direction qualifier can be used to control the order direction of the order: "ASC" for ascending and "DESC" for descending order. An example orderBy clause may be "createdAt asc, id desc". Defaults to "id asc".

Response

Responses include, but aren’t limited to:

StatusError CodeNotes
200 OKThe response body contains an array of objects with the specified fields for the object as documented in Query Response Format.

Query Response Format

Version 5 responses are formatted as JSON unless otherwise noted.

Read (Using GET)

Read requests are formatted as follows:

Parameters

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

Optional Header

A request can 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 aren’t limited to:

StatusError CodeNotes
200 OKThe response body contains fields for the object as documented in Response Format. A Last-Modified header is included on the response (see Response Headers).
304 Not ModifiedThe object hasn’t been updated since the time specified in an included If-Modified-Since request header. The response body is empty.

Create (Using POST)

Create requests are formatted as follows:

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

Parameters

ParameterRequiredDescription
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 subobjects.

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 - The input representation for the object (specifying fields and their values).
  • file - The file data that corresponds with the object.

Input Representation

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

Response

Responses include, but aren’t limited to:

StatusError CodeNotes
201 CreatedThe object was successfully created. The response body contains fields for the object as documented in Response Format. The response also contains 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:

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

Parameters

ParameterRequiredDescription
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 subobjects.

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:

  • input - The input representation for the object (specifying fields and their values).
  • file - The file data that corresponds with the object.

If the update includes only fields and not a file, a multipart request body isn’t needed. This fact 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.

Fields that are omitted are left unchanged.

Response

Responses include, but aren’t limited to:

StatusError CodeNotes
200 OKThe object was successfully updated. The response body contains fields for the object as documented in Response Format.
204 No ContentThe object was successfully updated. Because no output fields were requested, the response body is 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 don’t cause related objects to be deleted.

Delete requests are formatted as follows:

Response

Responses include, but aren’t limited to:

StatusError CodeNotes
204 No ContentObject was successfully deleted. The response body is empty.
405 Method Not Allowed108Object couldn’t be deleted because it’s used in other places.

Response Format

Version 5 responses are formatted as JSON unless otherwise noted.

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

Response Headers

HeaderDescription
Last-ModifiedDate that the object was last modified. (Sent only for GET requests.)
Pardot-WarningIncluded 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

ValueDescription
201;Record In Recycle BinThe 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 rulesSome values have been omitted from the API response because the requesting user doesn’t have sufficient access rights to see the omitted data.
203;Record count for nextPageToken sequence has been exceeded. No page token returned.The API has reached the limit for the sequence of page tokens generated for the initial starting query. See Pagination

Data Types

Fields can be of the following data types:

TypeNotes
StringString of characters.
IntegerNumber that must not contain a decimal point.
BooleanThe value true or false.
DateTimeISO 8601 formatted date and time (including timezone offset).
ObjectSome fields are references to another object. In these cases, responses can contain fields of the referenced object. These fields are read-only. Data is a JSON object containing fields that were specified in the fields parameter using dot-delimited notation.

Error Responses

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

Response statuses include, but aren’t limited to:

StatusNotes
400 Bad RequestPossible reasons include missing required parameters.
404 Not FoundObject with the given ID doesn’t exist or is in the recycle bin.
405 Method Not AllowedThe operation can’t be performed because the user has insufficient access rights, or a condition exists that prevents the operation from being performed.

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

Pagination

A query returns a nextPageToken field when the server can provide more data using the same set of filters, limit, and orderBy provided in the original query.

The next query includes only the required set of fields, and the nextPageToken returned by the server in the previous call. Omit other query parameters. Pardot will provide a new nextPageToken that can be used to retrieve the next data set until no more data is available or the limit of 100,000 records is reached.

When a page token is returned by the server, it provides a nextPageUrl value as a convenience string. This string can be used to retrieve the next set of data without having to build the request again.

If a nextPageToken is used twice, the same result set is returned if the data hasn’t changed.

Restrictions and Assumptions

  • The nextPageToken value returned expires after 4 hours, then the service rejects the page token and returns an error.

  • A page token isn’t returned if an offset is specified in the query.

  • A page token isn’t returned if the result set size is less than the limit parameter.

  • The pagination feature has a limit of 100,000 records. When a query reaches the limit it doesn't generate a new nextPageToken and a warning header is returned. See Response headers.

  • When a page token is sent, only the fields parameter can be specified. The following query parameters are invalid when passed with a page token and a (400) BAD_REQUEST status is returned.

    • orderBy
    • offset
    • limit
    • any filter