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.
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 |
Field | Type | Description |
---|---|---|
name | String | Name of the object for identification in Account Engagement. |
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. |
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. |
Retrieve a single list object following the conventions described in the Version 5 Overview.
Example request:
Example response:
Create a list following the conventions described in the Version 5 Overview.
Example request:
Example response:
Updating a list follows the conventions described in Version 5 Overview.
Example request:
Example response:
Deleting a list membership follows the conventions described in Version 5 Overview.
Example request:
Example response:
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.
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:
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:
Example response:
Adds a Tag to the List object, which creates a TaggedObject.
Example Request
Example Response
Remove a tag from a List object. When you remove a tag, the associated TaggedObject record is deleted.
Example Request
Example Response
Returns code 204 no content
.