List Object

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.

The API to access the List object follows the conventions described in Version 5 Overview.

Supported Operations

Operation	HTTP Verb	URL Format	Ability Requirements
Read	`GET`	`https://pi.pardot.com/api/v5/objects/lists/<id>?<params>`	Marketing > Segmentation > Lists > View
Create	`POST`	`https://pi.pardot.com/api/v5/objects/lists?<params>`	Marketing > Segmentation > Lists > Create
Update	`PATCH`	`https://pi.pardot.com/api/v5/objects/lists/<id>?<params>`	Marketing > Segmentation > Lists > Create
Delete	`DELETE`	`https://pi.pardot.com/api/v5/objects/lists/<id>`	Marketing > Segmentation > Lists > Delete
Query	`GET`	`https://pi.pardot.com/api/v5/objects/lists?<params>`	Marketing > Segmentation > Lists > View
Add Tag	`POST`	`https://pi.pardot.com/api/v5/objects/lists/<id>/do/addTag`	Marketing > Segmentation > Lists > Create AND Marketing > Segmentation > Tags > Create
Remove Tag	`POST`	`https://pi.pardot.com/api/v5/objects/lists/<id>/do/removeTag`	Marketing > Segmentation > Lists > Create AND Marketing > Segmentation > Tags > Create

Fields

Required Editable Fields

Field	Type	Description
`name`	String	Name of the object for identification in Account Engagement.

Optional Editable Fields

Field	Type	Description
`description`	Boolean	A description of the list object.
`title`	String	The name of the list object.
`isPublic`	Boolean	Indicates whether the list is public. If the value is `true`, the list is public.
`folderId`	Integer	ID of the folder containing this object. Uses the asset type’s uncategorized folder if not specified on create.
`campaignId`	Integer	Account Engagement campaign related to this object. Uses `null` if not specified on create.

Read-Only Fields

Field	Type	Description
`id`	Integer	ID of this object.
`isDeleted`	Boolean	True if the object is in the recycle bin in Account Engagement.
`isDynamic`	Boolean	True if the list is dynamic.
`createdAt`	DateTime	Creation time of this object.
`updatedAt`	DateTime	Last updated time for the object.
`createdById`	Integer	ID of the user who created the object.
`updatedById`	Integer	ID of the user who last updated the object.
`createdBy`	User	User object representing the user who created the object. See documentation for User for fields.
`updatedBy`	User	User object representing the user who last updated the object. See documentation for User for fields.
`campaign`	Campaign	Campaign object representing the campaign that was set on Create. See documentation for Campaign for fields.
`folder`	Folder	JSON object representing the folder for this object. See documentation for Folder for fields.

List Read

Retrieve a single list object following the conventions described in the Version 5 Overview.

Example request:

1GET /api/v5/objects/lists/101?fields=id,name
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example response:

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "id": 232130,
5    "name": "My List"
6}

List Create

Create a list following the conventions described in the Version 5 Overview.

Example request:

1POST /api/v5/objects/lists?fields=id,name,description,title,createdById,updatedById,createdAt,updatedAt,folderId,isDeleted HTTP/1.1
2Host: pi.demo.pardot.com
3Authorization: Bearer XXXXXXX
4Content-Length: 200
5
6{
7    "name": "List Name",
8    "description": "Enter Description of the List",
9    "title": "Enter Public Facing Text Here",
10    "isPublic": true,
11    "campaignId" : 7517,
12    "folderId" : 15911
13}

Example response:

1HTTP/1.1 201 Created
2Content-Type: application/json
3{
4    "id": 242713,
5    "createdAt": "2022-06-20T14:13:10-07:00",
6    "createdById": 3132592,
7    "description": "Enter Description of the List",
8    "folderId": 15911,
9    "isDeleted": false,
10    "name": "List Name",
11    "title": "Enter Public Facing Text Here",
12    "updatedAt": "2022-06-20T14:13:10-07:00",
13    "updatedById": 3132592
14}

List Update

Updating a list follows the conventions described in Version 5 Overview.

Example request:

1PATCH /api/v5/objects/lists/242713?fields=id,name,description,title,createdById,updatedById,createdAt,updatedAt,folderId,isDeleted HTTP/1.1
2Host: pi.demo.pardot.com
3Authorization: Bearer xxxxxx
4Content-Type: application/json
5Content-Length: 174
6{
7    "name": "updated name",
8    "description" : "updated description",
9    "title": "updated title",
10    "isPublic": false,
11    "campaignId": 7517,
12    "folderId": 15911
13}

Example response:

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "id": 242713,
5    "createdAt": "2022-06-20T14:13:10-07:00",
6    "createdById": 3132592,
7    "description": "updated description",
8    "folderId": 15911,
9    "isDeleted": false,
10    "name": "updated name",
11    "title": "updated title",
12    "updatedAt": "2022-06-20T14:16:08-07:00",
13    "updatedById": 3132592
14}

List Delete

Deleting a list membership follows the conventions described in Version 5 Overview.

Example request:

1DELETE /api/v5/objects/lists/242713 HTTP/1.1
2Host: pi.demo.pardot.com
3Authorization: Bearer XXXXX

Example response:

1HTTP/1.1 204 No Content

List Query

Retrieving a collection of list follows the conventions described in Version 5 Overview.

Retrieve a collection of lists follows the conventions described in the Version 5 Overview.

Sortable Fields

When executing a query, the following fields can be specified in the orderBy parameter. See the conventions for query described in the Version 5 Overview.

id
createdAt
updatedAt

Example request:

1GET /api/v5/objects/lists?fields=id,name&orderBy=id
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example response:

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "values": [
5        {
6            "id": 101,
7            "name": "My List"
8        }
9    ]
10}

Filtering Results

When executing a query, the following parameters can be used to filter the returned results. These parameters can be specified in the request along with any shared parameters defined in Version 5 Overview. When specifying more than one parameter, all parameters must match the record in order for it to be returned in the results.

Parameter	Description
`id`	Returns any list where ID is equal to the given integer value.
`idList`	Returns any list where ID is included in the given list of values.
`idGreaterThan`	Returns any list where ID is greater than the specified value, non-inclusive.
`idGreaterThanOrEqualTo`	Returns any list where ID is greater than or equal to the specified value.
`idLessThan`	Returns any list where ID is less than the specified value, non-inclusive.
`idLessThanOrEqualTo`	Returns any list where ID is less than or equal to the specified value.
`name`	Returns any list where Name is equal to the given string value.
`createdAt`	Returns any list where CreatedAt is equal to the given datetime value.
`createdAtAfter`	Returns any list where CreatedAt is after the given datetime value, non-inclusive.
`createdAtAfterOrEqualTo`	Returns any list where CreatedAt is after or equal to the given datetime value.
`createdAtBefore`	Returns any list where CreatedAt is before the given datetime value, non-inclusive.
`createdAtBeforeOrEqualTo`	Returns any list where CreatedAt is before or equal to the given datetime value.
`updatedAt`	Returns any list where UpdatedAt is equal to the given datetime value.
`updatedAtAfter`	Returns any list where UpdatedAt is after the given datetime value, non-inclusive.
`updatedAtAfterOrEqualTo`	Returns any list where UpdatedAt is after or equal to the given datetime value.
`updatedAtBefore`	Returns any list where UpdatedAt is before the given datetime value, non-inclusive.
`updatedAtBeforeOrEqualTo`	Returns any list where UpdatedAt is before or equal to the given datetime value.
`deleted`	Determines whether to return deleted records. The value can be `false` (default), `true`, or `all`.

Example request:

1GET /api/v5/objects/lists?fields=id,name&orderBy=id desc&idGreaterThan=200&idLessThan=300
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example response:

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "values": [
5        {
6            "id": 283,
7            "name": "My List 1"
8        },
9        {
10            "id": 282,
11            "name": "My List 2"
12        },
13        {
14            "id": 239,
15            "name": "My List 3"
16        },
17        {
18            "id": 202,
19            "name": "My List 4"
20        }
21    ]
22}

Add Tag

Adds a Tag to the List object, which creates a TaggedObject.

Example Request

1POST https://pi.pardot.com/api/v5/objects/lists/1000/do/addTag
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json
5
6{
7    "tagId": 100
8}

Example Response

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "id": 610,
5    "createdAt": "2024-09-23T18:26:49-04:00",
6    "createdById": 250,
7    "objectId": 1000,
8    "objectType": "list",
9    "tagId": 100
10}

Remove Tag

Remove a tag from a List object. When you remove a tag, the associated TaggedObject record is deleted.

Example Request

1POST https://pi.pardot.com/api/v5/objects/lists/1000/do/removeTag
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json
5
6{
7    "tagId": 100
8}

Example Response

Returns code 204 no content.