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

List Resources

A list is a group of prospects that you can use to send list emails or to feed engagement programs. Learn more about lists in Salesforce Help.

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

Resource Name	Operation	Description
List Create	`POST`	Create a list record.
List Delete	`DELETE`	Delete a list record.
List Read	`GET`	Request information for a single list.
List Query	`GET`	Request information for the lists that match the specified criteria.
List Update	`POST`	Update a list's information, including list fields, list subscription, and custom fields.

List Create

Create a list with the specified fields.

URI

/api/list/version/3/do/create?...

Parameters

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

Example

Create a list with the name New List and the description Likely Widget Customers:

POST /api/list/version/3/do/create?format=json HTTP/1.1
Host: pi.pardot.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <ACCESS_TOKEN>
Pardot-Business-Unit-Id: <BUSINESS_UNIT_ID>

name=New List&title=New List&description=Likely Widget Customers

List Delete

Delete the specified list.

URI

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

Replace <ID> with the Pardot list ID.

List Read

Request information for a single list.

URI

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

Replace <ID> with the Pardot list ID.

Example

Request information for the list with ID 12345.

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

List Query

Request information about the lists that match the specified criteria. You can specify which lists and which fields to request. A maximum of 200 lists are returned, unless you specify the output as mobile. If you specify the output as mobile, then all lists are returned.

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

URI

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

Parameters to Select Lists

Use these parameters to specify which lists 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 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 lists created after the specified date and time. Example: To request lists created in 2020, use `/api/lists/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 lists created before the specified date and time. Doesn’t include lists created at the specified time. `<custom_time>` Example: to request lists created before today (but not created today), use `/api/list/version/3/do/query?created_before=today`.
`id_greater_than`	`integer`	Any positive integer	Request lists that have a Pardot ID greater than the specified number.
`id_less_than`	`integer`	Any positive integer	Request lists that have a Pardot ID less than the specified number.
`name`	`string`	string	Request lists with the specified name.
`updated_after`	`string`	`today`, `yesterday`, `last_7_days`, `this_month`, `last_month`, `<custom_time>`	Request lists 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 lists that were last updated before the specified date and time.

Parameters to Specify Which Results Are Returned

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

Parameter	Type	Possible Values	Description
`limit`	`integer`	Any integer from 1 through 200.	The number of lists to return. Default value is 200.
`offset`	`integer`	Any positive integer	The number of lists to omit from the response (the number to "skip over"). Example: Retrieve a set of list records, omitting the 50 most recently updated lists. Sort the query by the `updated_at` field and use offset=50: `/api/list/version/3/do/query?sort_by=updated_at&offset=50`
`sort_by`	`string`	`created_at`, `id`, `name`, `updated_at`	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 lists' `created_at` timestamps.
`id`	ascending	Sort the results by the lists' `id` fields.
`name`	ascending	Sort the results by the lists' `name` fields.
`updated_at`	descending	Sort the results by the lists' `updated_at` timestamps.

Example

Request a set of list records, sorted in ascending order by the time of last update.

/api/list/version/3/do/query?sort_order=ascending&sort_by=updated_at

List Update

Update the value of a list'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.

URI

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

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

Parameters

You can use any list field as a parameter. For information about list fields, see List.

Example

To change a list's name to "VIP List" and change this list title to Learn about Widgets, use the following command:

/api/list/version/3/do/update/id/485336?name=VIP List&title=Learn about Widgets

XML Response

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

XML Response for List Query

<rsp stat="ok" version="1.0">
    <result>
        <total_results>...</total_results>
        <list>...</list>
        <list>...</list>
        <list>...</list>
    </result>
</rsp>

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

XML Response for List Read

<rsp stat="ok" version="1.0">
    <list>
        <id>752</id>
        <name>Monthly Newsletter</name>
        <is_public>true</is_public>
        <is_dynamic>false</is_dynamic>
        <title>Newsletter</title>
        <description>For public lists, an optional description may be used to explain to the prospect why they might want to include this list in their subscription preferences.</description>
        <is_crm_visible>false</is_crm_visible>
        <created_at>2014-02-11 15:42:36</created_at>
        <updated_at>2014-03-06 15:28:41</updated_at>
    </list>
</rsp>

Tag	Description
`<list>`	Parent tag. The information for a single list. For information about list fields, see List.