Pardot's developer content is getting a makeover! Starting July 12th, you’ll be redirected to our new site.

List Membership Resources

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.

Note: 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.

List Membership Create

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

URI

/api/listMembership/version/3/do/create/list_id/<list_id>/prospect_id/<prospect_id>?

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

/api/listMembership/version/3/do/create/list_id/100000/prospect_id/12345

List Membership Delete

Delete the specified list membership records.

URI

/api/listMembership/version/3/do/delete/id/<ID>

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

/api/listMembership/version/3/do/read/id/<ID>?..

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

/api/listMembership/version /4/do/read/list_id/<list_id>/prospect_id/<prospect_id>?...

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

Example

Request information for the list membership with ID 12345.

/api/listMembership/version/3/do/read/id/12345

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

/api/listMembership/version/4/do/read/list_id/12345/prospect_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

/api/listMembership/version/3/do/query?...

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:

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/3/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/3/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 a Pardot ID greater than the specified number.
id_less_than integer Any positive integer Request list memberships that have a Pardot ID less than the specified number.
list_id integer Any valid list id Request list memberships with the specified Pardot 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.

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.

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/3/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.

Sort Order

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

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.

/api/listMembership/version/3/do/update/id/<ID>?...

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

/api/listMembership/version/3/do/update/list_id/<LIST_ID>/prospect_id/<PROSPECT_ID>

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


<rsp stat="ok" version="1.0">
    <result>
        <total_results>...</total_results>
        <list_membership>...</list_membership>
        <list_membership>...</list_membership>
        <list_membership>...</list_membership>
    </result>
</rsp>
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.

XML Response for List Membership Read

<rsp stat="ok" version="1.0">
    <list_membership>
        <id>1</id>
        <list_id>8</list_id>
        <prospect_id>622</prospect_id>
        <opted_out>false</opted_out>
        <created_at>2013-08-30 16:54:42</created_at>
        <updated_at>2014-10-24 14:04:47</updated_at>
    </list_membership>
</rsp>
Tag Description
<list_membership> Parent tag. The information for a single list membership. For information about list membership fields, see List Membership.