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 may 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 - on collection endpoint to query for objects.
• GET - read an object.
• 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.

Responses include, but aren’t limited to:

Version 5 responses are formatted as JSON unless otherwise noted.

Read requests are formatted as follows:

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:

Create requests are formatted as follows:

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

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.

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

Responses include, but aren’t limited to:

Update requests are formatted as follows:

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

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:

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:

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.

Fields can be of the following 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:

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, and the nextPageToken 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.

The next query includes only the required set of fields, plus the nextPageToken returned by the server in the previous call. Omit other query parameters. Account Engagement provides a new nextPageToken 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 are supported only on read 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: