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 Name | Operation | Description |
|---|---|---|
| List Membership Create | POST | Create a list membership record. |
| List Membership Delete | DELETE | Delete a list membership record. |
| List Membership Read | GET | Request information for a single list membership. |
| List Membership Query | GET | Request information for the list memberships that match the specified criteria. |
| List Membership Update | POST | Update 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.
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:
- Parameters must be URL-encoded.
- Dates and times must use GNU Date Input Syntax (yyyy-mm-dd:hh:ss
). - For a full listing of list membership fields see Object Field References.
| Parameter | Type | Possible Values | Description |
|---|---|---|---|
created_after | string | today, 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/4/do/query?created_after=2019-12-31 24:59:59. |
created_before | string | today, 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/4/do/query?created_before=today. |
deleted | string | true, false | If true, request list memberships that are deleted. Otherwise, request list memberships that aren’t deleted. Default value is false. |
id_greater_than | integer | Any positive integer | Request list memberships that have an Account Engagement ID greater than the specified number. |
id_less_than | integer | Any positive integer | Request list memberships that have an Account Engagement ID less than the specified number. |
list_id | integer | Any valid list id | Request list memberships with the specified Account Engagement list ID. |
updated_after | string | today, yesterday, last_7_days, this_month, last_month, <custom_time> | Request list memberships that were last updated after the specified date and time. |
updated_before | string | today, 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.
| Parameter | Type | Possible Values | Description |
|---|---|---|---|
limit | integer | Any integer from 1 through 200. | The number of list memberships to return. Default value is 200. |
offset | integer | Any positive integer | The 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/4/do/query?offset=50&sort_by=created_at |
sort_by | string | created_at, id | The field by which the results are sorted. See Sort Order. |
sort_order | string | ascending, descending | The 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.
| Value | Default Sort Order | Description |
|---|---|---|
created_at | descending | Sort the results by the list memberships' created_at timestamps. |
id | ascending | Sort 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.
| Tag | Description |
|---|---|
<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. |
| Tag | Description |
|---|---|
<list_membership> | Parent tag. The information for a single list membership. For information about list membership fields, see List Membership. |