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. This is typically most visible in scenarios where the caller updates data and then tries to read it back immediately. In this scenario, the update is made to the primary data, which may not have replicated to the cache immediately, resulting in a brief inconsistency. If the caller is pulling data regularly, this should self-resolve, as all updates flow to the cache. If the cache is more than 60 seconds behind, calls will be 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.
| Parameter | Required | Description |
|---|---|---|
fields | X | A comma-delimited list of fields to return. Use dot-delimited notation (<field-name>.<sub-object-field-name>) to specify fields on sub-objects. |
deleted | Specify "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. | |
limit | The number of items to return. This must be a positive integer up to 1000. Defaults to 200. | |
offset | Deprecated. The index of the first record to return. This must be a positive integer up to 2000. If an offset more than 2000 is required, use the Export API instead. Defaults to 0. | |
orderBy | A 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. An example orderBy clause may be "createdAt asc". Defaults to "id asc". |
Responses include, but aren’t limited to:
| Status | Error Code | Notes |
|---|---|---|
200 OK | The 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:
Note: For singleton objects, the id field is not present and the object-collection in the path is replaced by the singular object:
| Parameter | Required | Description |
|---|---|---|
fields | X | 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:
| Status | Error Code | Notes |
|---|---|---|
200 OK | The 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 Modified | The 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.
| Parameter | Required | Description |
|---|---|---|
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 a JSON formatted input representation must be included to specify fields for the object.
Responses include, but aren’t limited to:
| Status | Error Code | Notes |
|---|---|---|
201 Created | The 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 Content | The 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.
| Parameter | Required | Description |
|---|---|---|
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.
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.
Responses include, but aren’t limited to:
| Status | Error Code | Notes |
|---|---|---|
200 OK | The object was successfully updated. The response body contains fields for the object as documented in Response Format. | |
204 No Content | The 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:
| Status | Error Code | Notes |
|---|---|---|
204 No Content | Object was successfully deleted. The response body is empty. | |
405 Method Not Allowed | 108 | Object 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.
| Header | Description |
|---|---|
Last-Modified | Date that the object was last modified. (Sent only for GET requests.) |
Pardot-Warning | Included 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. |
| Value | Description |
|---|---|
201;Record In Recycle Bin | The 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 rules | Some 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:
| Type | Notes |
|---|---|
| String | String of characters. |
| Integer | Number that must not contain a decimal point. |
| Boolean | The value true or false. |
| DateTime | ISO 8601 formatted date and time (including timezone offset) following only this format: YYYY-MM-DDTHH:MM:SS+/-HH:MM. |
| Object | Some 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. |
| Array | Fields 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:
| Status | Notes |
|---|---|
400 Bad Request | Possible reasons include missing required parameters. |
404 Not Found | Object with the given ID doesn’t exist or is in the recycle bin. |
405 Method Not Allowed | The 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).
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. Account Engagement 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.
-
The
nextPageTokenvalue 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
limitparameter. -
The pagination feature has a limit of 100,000 records. When a query reaches the limit it doesn't generate a new
nextPageTokenand 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
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
fieldsparameter, specify the name of the collection, similar to how relationships are selected. - If the collection references an object or representation, the collection name must be followed by a field, using dot notation.
- Collections can reference fields and relationships. You can't select a collection within a collection.
Example requests
Example Response