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.

List Membership Resources

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.

List Membership Create

Create a list membership by specifying the Pardot list ID and Pardot prospect ID.

URI

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

Parameters

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

Example

List Membership Delete

Delete the specified list membership records.

URI

Replace <ID> with the Pardot ID of the list membership record.

List Membership Read

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

URIs

Replace <ID> with the Pardot ID of the list membership.

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

Example

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.

List Membership Query

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.

URI

Parameters to Select List Memberships

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 a Pardot ID greater than the specified number.
id_less_thanintegerAny positive integerRequest list memberships that have a Pardot ID less than the specified number.
list_idintegerAny valid list idRequest list memberships with the specified Pardot 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.

Parameters to Specify Which Results Are Returned

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.

Sort Order

Use sort_by to specify which field Pardot 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.

List Membership Update

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.

URIs

You can use the Pardot 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 Pardot ID of the list membership.

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

Parameters

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

Example

XML Response

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.

XML Response for List Membership Query

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.

XML Response for List Membership Read

TagDescription
<list_membership>Parent tag. The information for a single list membership. For information about list membership fields, see List Membership.