Lists

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

OperationHTTP VerbURL FormatAbility Requirements
ReadGEThttps://pi.pardot.com/api/v5/objects/lists/<id>?<params>Marketing > Segmentation > Lists > View ability
CreatePOSThttps://pi.pardot.com/api/v5/objects/lists?<params>Marketing > Segmentation > Lists > Create/Edit ability
UpdatePATCHhttps://pi.pardot.com/api/v5/objects/lists/<id>?<params>Marketing > Segmentation > Lists > Create/Edit ability
DeleteDELETEhttps://pi.pardot.com/api/v5/objects/lists/<id>Marketing > Segmentation > Lists > Delete ability
QueryGEThttps://pi.pardot.com/api/v5/objects/lists?<params>Marketing > Segmentation > Lists > View ability

Fields

Required Editable Fields

FieldTypeDescription
nameStringName of the object for identification in Pardot.

Optional Editable Fields

FieldTypeDescription
descriptionBooleanDescription of the list object.
titleStringTitle of the list object.
isPublicBooleanTrue if the list is public.
folderIdIntegerID of the folder containing this object. Uses the asset type's uncategorized folder if not specified on create.
campaignIdIntegerPardot campaign related to this object. Uses null if not specified on create.

Read-Only Fields

FieldTypeDescription
idIntegerID of this object.
isDeletedBooleanTrue if the object is in the recycle bin in Pardot.
isDynamicBooleanTrue if the list is dynamic.
createdAtDateTimeCreation time of this object.
updatedAtDateTimeLast updated time for the object.
createdByIdIntegerID of the user who created the object.
updatedByIdIntegerID of the user who last updated the object.
createdByUserUser object representing the user who created the object. See documentation for User for fields.
updatedByUserUser object representing the user who last updated the object. See documentation for User for fields.
campaignCampaignCampaign object representing the campaign that was set on Create. See documentation for Campaign for fields.
folderFolderJSON 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:

Example response:

List Query

Retrieving a collection of list follows the conventions described in 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:

Example response:

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.

ParameterDescription
idReturns any list where ID is equal to the given integer value.
idGreaterThanReturns any list where ID is greater than the specified value, non-inclusive.
idGreaterThanOrEqualToReturns any list where ID is greater than or equal to the specified value.
idLessThanReturns any list where ID is less than the specified value, non-inclusive.
idLessThanOrEqualToReturns any list where ID is less than or equal to the specified value.
nameReturns any list where Name is equal to the given string value.
createdAtReturns any list where CreatedAt is equal to the given datetime value.
createdAtAfterReturns any list where CreatedAt is after the given datetime value, non-inclusive.
createdAtAfterOrEqualToReturns any list where CreatedAt is after or equal to the given datetime value.
createdAtBeforeReturns any list where CreatedAt is before the given datetime value, non-inclusive.
createdAtBeforeOrEqualToReturns any list where CreatedAt is before or equal to the given datetime value.
updatedAtReturns any list where UpdatedAt is equal to the given datetime value.
updatedAtAfterReturns any list where UpdatedAt is after the given datetime value, non-inclusive.
updatedAtAfterOrEqualToReturns any list where UpdatedAt is after or equal to the given datetime value.
updatedAtBeforeReturns any list where UpdatedAt is before the given datetime value, non-inclusive.
updatedAtBeforeOrEqualToReturns any list where UpdatedAt is before or equal to the given datetime value.

Example request:

Example response: