List Object

A list is a group of prospects that you can use to send list emails or to feed engagement programs. Learn more about lists in Salesforce Help.

Include the authentication header with every request. For information on how to authenticate, see Authentication.

Resource NameOperationDescription
List CreatePOSTCreate a list record.
List DeleteDELETEDelete a list record.
List ReadGETRequest information for a single list.
List QueryGETRequest information for the lists that match the specified criteria.
List UpdatePOSTUpdate a list's information, including list fields, list subscription, and custom fields.

Create a list with the specified fields.

You can use any list field as a parameter. For a list of list fields, see List in the object field reference.

Create a list with the name New List and the description Likely Widget Customers:

Delete the specified list.

Replace <ID> with the Account Engagement list ID.

Request information for a single list.

Replace <ID> with the Account Engagement list ID.

Request information for the list with ID 12345.

Request information about the lists that match the specified criteria. You can specify which lists and which fields to request. A maximum of 200 lists are returned, unless you specify the output as mobile. If you specify the output as mobile, then all lists are returned.

To request information about a specific list, use List Read.

Use these parameters to specify which lists are returned. Parameters can be used in any combination and in any order unless otherwise specified.

Notes:

ParameterTypePossible ValuesDescription
created_afterstringtoday, yesterday, last_7_days, this_month, last_month,<custom_time>Request lists created after the specified date and time. Example: To request lists created in 2020, use /api/lists/version/4/do/query?created_after=2019-12-31 24:59:59.
created_beforestringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Request lists created before the specified date and time. Doesn’t include lists created at the specified time. <custom_time> Example: to request lists created before today (but not created today), use /api/list/version/4/do/query?created_before=today.
id_greater_thanintegerAny positive integerRequest lists that have an Account Engagement ID greater than the specified number.
id_less_thanintegerAny positive integerRequest lists that have an Account Engagement ID less than the specified number.
namestringstringRequest lists with the specified name.
updated_afterstringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Request lists that were last updated after the specified date and time.
updated_beforestringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Request lists that were last updated before the specified date and time.

Use these parameters to specify which list fields are returned, and how the lists are sorted.

ParameterTypePossible ValuesDescription
limitintegerAny integer from 1 through 200.The number of lists to return. Default value is 200.
offsetintegerAny positive integerThe number of lists to omit from the response (the number to "skip over"). Example: Retrieve a set of list records, omitting the 50 most recently updated lists. Sort the query by the updated_at field and use offset=50: /api/list/version/4/do/query?sort_by=updated_at&offset=50
sort_bystringcreated_at, id, name, updated_atThe field by which the results are sorted. See Sort Order.
sort_orderstringascending, descendingThe sort order. The default value depends on which sort_by value you specify. See Sort Order.

Use sort_by to specify which field Account Engagement uses to sort the results. Different fields have different default sort orders.

ValueDefault Sort OrderDescription
created_atdescendingSort the results by the lists' created_at timestamps.
idascendingSort the results by the lists' id fields.
nameascendingSort the results by the lists' name fields.
updated_atdescendingSort the results by the lists' updated_at timestamps.

Request a set of list records, sorted in ascending order by the time of last update.

Update the value of a list's fields. Fields that aren’t specified in the request aren’t changed. To clear a field, use a null value.

Returns an updated version of the list.

Replace <ID> with the Account Engagement ID of the list.

You can use any list field as a parameter. For information about list fields, see List.

To change a list's name to "VIP List" and change this list title to Learn about Widgets, use the following command:

The XML response for a query request contains information about multiple lists. The XML response for a read request contains information about a single list.

TagDescription
<result>Parent tag. Contains the lists that match the parameters specified in your query.
<total_results>The number of lists selected by the query. Note: The query request returns a maximum of 200 lists. If your query matches more than 200 lists, you can make several requests to retrieve all matching records.
<list>The information for a single list. For information about list fields, see List.
TagDescription
<list>Parent tag. The information for a single list. For information about list fields, see List.