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.

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.

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

objectXThe object type to be returned by the API request
opXThe operation to be performed on the specified object type
id_fieldXThe field to be used as the identifier for the specified object
idXThe identifier for the specified objects
access_tokenXThe access token obtained during Authentication
pardot_business_unit_idXThe Account Engagement business unit. For details see Authentication
formatThe API data format: either xml (default) or json
paramsParameters 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

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.

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.