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/4/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/4/do/create/list_id/10000/prospect_id/12345

List Membership Delete

Delete the specified list membership records.

URI

/api/listMembership/version/4/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/4/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/4/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/4/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:

Parameters must be URL-encoded.
Dates and times must use GNU Date Input Syntax (yyyy-mm-dd:hh:ss:mm).
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 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/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.

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/4/do/update/id/<ID>?...

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

/api/listMembership/version/4/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.