List Membership Object

A list is a group of prospects that you can use to send list emails or to feed engagement programs. Use list membership resources to add and remove prospects to your static email lists, and to learn which prospects belong to which lists. Learn more about list membership in Salesforce Help.

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

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

Create a list membership by specifying the Account Engagement list ID and Account Engagement prospect ID.

Replace <list_id> with the Account Engagement ID of the list, and <prospect_id> with the Account Engagement ID of the prospect.

You can use any list membership field as a parameter. For a list of list membership fields, see List Membership.

Delete the specified list membership records.

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

Request information for a single list membership. You can use the Account Engagement list membership ID. Or, you can use the list ID and the prospect ID.

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

Replace <list_id> with the Account Engagement ID of the list. Replace <prospect_id> with the Prospect ID that you want list information about.

Request information for the list membership with ID 12345.

Request information for the list membership with ID 12345. Only return list membership information for the prospect with ID 5678.

Request information about the list memberships that match the specified criteria. A maximum of 200 list memberships are returned, unless you specify the output as mobile. If you specify the output as mobile, then all list memberships are returned.

Note: To request information about a specific list membership, use List Membership Read.

Use these parameters to specify which list memberships 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 list memberships created after the specified date and time. Example: To request list memberships created in 2020, use /api/listMembership/version/3/do/query?created_after=2019-12-31 24:59:59.
created_beforestringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Request list memberships created before the specified date and time. Doesn’t include list memberships created at the specified time. Example: to request list memberships created before today (but not created today), use /api/listMembership/version/3/do/query?created_before=today.
deletedstringtrue, falseIf true, request list memberships that are deleted. Otherwise, request list memberships that aren’t deleted. Default value is false.
id_greater_thanintegerAny positive integerRequest list memberships that have an Account Engagement ID greater than the specified number.
id_less_thanintegerAny positive integerRequest list memberships that have an Account Engagement ID less than the specified number.
list_idintegerAny valid list idRequest list memberships with the specified Account Engagement list ID.
updated_afterstringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Request list memberships that were last updated after the specified date and time.
updated_beforestringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Request list memberships that were last updated before the specified date and time.

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

ParameterTypePossible ValuesDescription
limitintegerAny integer from 1 through 200.The number of list memberships to return. Default value is 200.
offsetintegerAny positive integerThe number of list memberships to omit from the response (the number to "skip over"). Example: Retrieve a list of list memberships, omitting the 50 most recently updated list memberships. Sort the query by the created_at field and use offset=50: /api/listMembership/version/3/do/query?offset=50&sort_by=created_at
sort_bystringcreated_at, idThe 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 list memberships' created_at timestamps.
idascendingSort the results by the list memberships' id fields.

Update the values in a list membership'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 membership.

You can use the Account Engagement list membership ID to specify the list membership to update. Or, you can use the list ID and the prospect ID.

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

Replace <ID> with the Account Engagement ID of the list, and <PROSPECT_ID> with the Account Engagement ID of the prospect.

You can use any list membership field as a parameter. For a list of list membership fields, see Object Field References.

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

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