Version 5

You can use version 5 of the Account Engagement 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.

For performance reasons, data returned by version 5 endpoints isn’t always real time. Behind the scenes, we build caches of customer data that can be used to fulfill requests. Data flows constantly from the primary dataset into the cache. If the cache is less than 60 seconds behind the real data, we use it to fulfill an API request. A delay is typically most visible when the caller updates data and then tries to read it back immediately. In such a scenario, the update is made to the primary data, which sometimes isn’t immediately replicated to the cache, resulting in a brief inconsistency. If the caller pulls data regularly, delays self-resolve, as all updates flow to the cache. If the cache is more than 60 seconds behind, calls are fulfilled from the primary data.

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

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

  • GET - retrieve information about an object, or query several objects.
  • POST - create an object.
  • PATCH - update an object.
  • DELETE - delete an object.

Query requests are formatted as follows:

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

ParameterDescription
fieldsRequired. A comma-delimited list of fields to return. Use dot-delimited notation (<field-name>.<sub-object-field-name>) to specify fields on subobjects.
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 that are moved to the recycle bin in Account Engagement when deleted.) Defaults to false.
limitThe number of items to return. The limit must be a positive integer up to 1000. It defaults to 200.
offsetDeprecated. The index of the first record to return. The offset must be a positive integer up to 2000. If an offset more than 2000 is required, use the Export API instead. Defaults to 0.
orderByA single field 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. For example, to sort by creation date in ascending order, use createdAt ASC. The default is id ASC.

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.

Version 5 responses are formatted as JSON unless otherwise noted.

Read requests are formatted as follows:

For singleton objects, the Id field isn’t present and the object-collection in the path gets replaced by the singular object:

GET /api/v5/objects/<object>?<params> HTTP/1.1
Host: pi.pardot.com
Authorization: Bearer <access-token>
ParameterDescription
fieldsRequired. A 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 Account Engagement when deleted.)

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.

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 requests are formatted as follows:

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

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.

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.

When creating an object, include a JSON-formatted input representation that specifies fields for the object.

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.
204 No ContentThe record was created, but the API user doesn’t have permissions to read the record.

Update requests are formatted as follows:

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

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.

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.

To update an object, include a JSON-formatted input representation that specifies fields for the object.

Fields that are omitted are left unchanged.

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. Either no output fields were requested, so the response body is empty, or the API user doesn’t have permission to view this record after it was updated.

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

Delete requests don’t cause related objects to be deleted.

Delete requests are formatted as follows:

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.

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.

HeaderDescription
If-Modified-SinceA 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.
X-Return-Api-UsageA request can set the optional X-Return-Api-Usage header as 1 or true to retrieve API Usage information returned with the x-api-usage response header.
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.
x-api-usageThe number of API calls made in the last day over the maximum calls the account can make per day.
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

Fields can be of the following data types:

TypeNotes
StringA string of characters.
IntegerA number that must not contain a decimal point.
BooleanThe value true or false.
DateTimeThe ISO 8601-formatted date and time (including time zone offset) using only the format YYYY-MM-DDTHH:MM:SS+/-HH:MM. To interpret When positive offsets in request parameters, the caller has to UrlEncode the value. For example, set "+05:00" as "%2b05:00".
ObjectSome fields contain references to another object, so responses sometimes 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.
ArrayFields that return an array of objects or primitive data types.

Error responses from version 5 of the Account Engagement 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).

The next query includes only the required set of fields, plus the nextPageToken field returned by the server in the previous call. Omit other query parameters. Account Engagement provides a new nextPageToken that’s used to retrieve the next dataset until no more data is available or the limit of 100,000 records is reached.

Page tokens returned by the server provide 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.

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

  • If you specify an offset in the query, it doesn’t return a page token.

  • If the result set size is less than the value of the limit parameter, the query doesn’t return a page token.

  • 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. These query parameters are invalid when they’re passed with a page token and a 400 BAD_REQUEST status is returned.

    • orderBy
    • offset
    • limit
    • any filter

Some objects can contain a collection of other objects, records, and data.

  • Collections aren’t supported on query operations.
  • To select a collection within the fields parameter, specify the name of the collection, similar to how relationships are selected.
  • If the collection references an object or representation, use dot notation to specify a field after the collection name.
  • Collections can reference fields and relationships. You can’t select a collection within a collection.

Example requests

Example Response

In Version 5 of the Account Engagement API, any object can have a relationship field. A relationship is a property on an object that references another object, denoted in the documentation by the field’s type. For example, Prospects have a relationship field called campaign, which links to the Campaign object.

Callers can take advantage of relationship fields to build their requests to retrieve data from multiple objects in a single response, reducing the need for multiple requests. Using the example above, we can query Prospects and include data from Campaigns.

Request:

Response:

Relationships can be chained for up to three object tracks. Multiple relationships can be used in a single request. The examples shown here consume only one API call.

Request:

Response: