Account Engagement has a new shiny REST API! Version 5 was built from the ground up to make integration easy for all customers and ISVs. With better REST standard adoption, stricter typing, and standardized input and output, I’m here to tell you that the time to upgrade is now.

Available for all accounts, regardless of AMPSEA

Access to the Account Engagement API versions 3 and 4 was gated by feature, specifically Allow Multiple Prospects with the Same Email Address (AMPSEA). Customers with AMPSEA enabled were migrated to version 4, whereas customers without AMPSEA had to use version 3. When building version 5, we wanted to eliminate this problem and provide a singular, unified API that all orgs can use. Thus, all orgs are eligible to use API version 5, provided they have API Access, as defined by the Pardot Edition. However, there are differences in how certain endpoints will respond based on AMPSEA. Let’s look at a few examples.

Response:

As you can see, querying prospects by email when AMPSEA is enabled may yield more than one result.

Querying prospects by email, non-AMPSEA

Response:

By contrast, when AMPSEA is not enabled, querying by email will yield a maximum of one result. In both configurations, querying by ID will yield no more than one result.

Field selection versus output formats

The Account Engagement API version 5 requires callers to specify the desired response fields for any request. The benefits here are multi-fold. First, data minimization — we don’t clutter the response with fields that the caller does not need. Second, performance — different fields can have different performance characteristics. For example, on the Email object, the htmlMessage field can have megabytes of data in it. Retrieving this field and transmitting it to the caller will waste time and resources if it is not needed. In a query use case, where up to 1000 rows can be returned, this single field could consume a gigabyte of data. To avoid the scenario where a query could time out, this field and others that can lead to unbounded data are only offered when reading a single record.

Relationships are another feature new to version 5. When combined with Field Selection, they offer a powerful tool for callers to craft responses to their needs. Similar to SOQL Relationships, they allow callers to query and structure data in a custom fashion. Prior versions forced callers to adopt one of four response formats: full, simple, mobile, or bulk. While convenient, these formats gave callers little control over which fields and relationships were exposed in the final dataset and often made hidden performance tradeoffs to optimize for one thing over another. When using relationships in combination with field selection, the caller is in control of exactly what data they want to receive.

Let’s look at how to leverage field selection and relationships together.

Prospect query with relationships

Response:

Here, you can see how we structured our fields parameter to include fields from the campaign and assignedTo relationships. As listed on the Prospects documentation, any field whose type is another object (represented by a hyperlink) can be called when querying or reading a record. Here, we’re calling the Campaign and User objects and specifying the fields that we want in the response.

Relationships can be chained or even recursive. Some objects, like Folder, have a reference to another Folder (the parent). We allow up to three relationship traversals per query.

Prospect query with nested relationships

Response:

Here, you can see a level of relational structure that was never possible with prior versions. The possibilities for mixing and combining data using the object tree in version 5 are vast.

Pagination

For large datasets, pagination plays a critical part in retrieving bulk data. Though we also offer export for large asynchronous datasets, sometimes users need to access bulk data in a synchronous fashion. Previous versions required users to manage their own pagination by keeping track of filter windows, or by using offset. Large offsets would often lead to performance problems.

With version 5 of the Account Engagement API, we wanted to build a new approach that offered reliable, fast pagination for many thousands of records without running into the problems encountered previously. Enter pagination. When performing a query on any object, the server will populate a nextPageToken field when there is more data available. The token encapsulates the filters, limit, and orderBy information. For convenience, a nextPageUrl is included in the result set with the token already appended. The consumer can continue to pull the data at the nextPageUrl until this field and the token is returned as null, at which point there will be no more data.

Using pagination, users can retrieve up to 100,000 records. Each page can contain up to 1000 records, based on the limit specified in the initial query. If data volumes exceed this limit, we recommend transitioning to the Export API.

JSON & REST native

If you’ve used versions 3 and 4 of the Account Engagement API, you probably remember that XML is the default output standard, and users have to request JSON if they want it. No more! Version 5 supports JSON by default.

Behind the scenes, there’s a real improvement happening here. Older versions actually constructed XML for all requests, regardless of the user’s requested format. Before sending the response, the XML would be converted to JSON if needed. The conversion process treated some XML entries as strings and others as JSON types. The process was brittle and would lead to edge cases where imperfect conversion could sometimes cause invalid JSON. Remediating this in a way that didn’t change expected behavior proved to be challenging, as bot submissions for objects like Visitors can come up with a wide array of data that will cause problems during conversion.

The best solution was to start from the ground up with JSON, so that’s exactly what we did. The net effect of supporting JSON types out of the box should make it easier for callers to integrate Pardot endpoints with Apex.

We hope you can make use of our new developer tooling and that you enjoy using these tools as much as we enjoy building them.

About the Author

Adil joined the Account Engagement (then Pardot) team at Salesforce in 2013, and he has been a member of the API Engineering team since 2018. He has contributed to the Version 5 framework, as well as the Import and Export APIs. Before joining the API team, Adil led internationalization efforts for the Japanese and European markets and helped lead the launch of Salesforce Engage.