Engagement Studio Program Object
The Engagement Studio Program API provides a programmatic way to copy Engagement Studio Programs across different Orgs and Business Units. It uses Account Engagement's existing API structures, patterns, and terminology.
The API access to the Engagement Studio Program object follows the conventions described in Version 5 Overview.
Include the authentication header with every request. For information on how to authenticate, see Authentication.
New Engagement Studio Programs created using the Create with File endpoint are created in the draft state. Though they are eligible for editing in the UI, individual program nodes cannot be edited via API. If a caller wants to make changes, changes must be made in the UI and a new structure file must be downloaded using the Download Program Structure endpoint.
When copying an Engagement Studio Program from a source business unit with custom configurations (such as Scoring Categories, External Activities, Email Templates, etc.) to a target business unit that doesn't have the same custom configurations, it is possible to create an invalid Engagement Studio Program. In this scenario, the Engagement Studio UI is used to detect and remove the invalid nodes. Pressing the Start button in the UI runs validations that catch and highlight invalid nodes. To successfully run the program, the user must manually edit or replace the invalid nodes with valid ones.
When copying an Engagement Studio Program with Actions and/or Rules that reference Custom Fields, the Engagement Studio Program API accurately assigns a matching Custom Field with the same fieldId and type from the target BU. If no match is found, the field is left blank for the user to select.
Failing nodes are highlighted during start validations.
| Operation | HTTP Verb | URL Format | Ability Requirements |
|---|---|---|---|
| Read | GET | https://pi.pardot.com/api/v5/objects/engagement-studio-programs/<id>?<params> | Marketing > Engagement Studio > Engagement Program > View |
| Query | GET | https://pi.pardot.com/api/v5/objects/engagement-studio-programs?<params> | Marketing > Engagement Studio > Engagement Program > View |
| Download Program Structure | GET | https://pi.pardot.com/api/v5/objects/engagement-studio-programs/<id>/download-program-structure | Marketing > Engagement Studio > Engagement Program > View |
| Create with File | POST | https://pi.pardot.com/api/v5/objects/engagement-studio-programs?<params> | Marketing > Engagement Studio > Engagement Program > Create/Edit |
| Field | Type | Description |
|---|---|---|
name | String | Name of the object for identification in Account Engagement. |
| Field | Type | Description |
|---|---|---|
folderId | Integer | ID of the folder containing this object. Uses the asset type's uncategorized folder if not specified on create. |
| Field | Type | Description |
|---|---|---|
id | Integer | ID of the object. |
status | Enum | The status of the program. See Engagement Studio Program State Enum. |
isDeleted | Boolean | True if the object is in the recycle bin in Account Engagement. |
salesforceId | String | SalesforceID of the object. |
description | String | Description of the object. |
businessHours | Business Hours Representation | Map representation of the program's business hours. |
prospectsMultipleEntry | Prospects Multiple Entry Representation | Map representation of the program's prospects' multiple entry options. |
schedule | Schedule Representation | Map representation of the program's schedule. |
scheduleCreatedById | Integer | ID of the user who created the program's schedule. |
scheduleCreatedBy | User | User object representing the user who created the program's schedule. See documentation for User for fields. |
recipientListIds | Array | Array containing the program's Recipient List IDs. |
suppressionListIds | Array | Array containing the program's Suppression List IDs. |
createdAt | DateTime | Creation time of the object. |
updatedAt | DateTime | Last update time of the object. |
createdById | Integer | ID of the user who created this object. |
updatedById | Integer | ID of the user who last updated this object. |
createdBy | User | User object representing the user who created this object. See documentation for User for fields. |
updatedBy | User | User object representing the user who last updated this object. See documentation for User for fields. |
| Field Name | Data Type | Description |
|---|---|---|
days | Array | Array containing the business days of the week. |
startTime | Time | The start time of the business day. |
endTime | Time | The end time of the business day. |
timezone | String | The timezone of the business hours. See list of all possible timezones |
| Field Name | Data Type | Description |
|---|---|---|
minimumDurationInDays | Integer | The minimum amount of days before a prospect can reenter the program |
maximumEntries | Integer | The maximum amount of times a prospect can reenter the program. Unlimited entries are represented as null. |
| Field Name | Data Type | Description |
|---|---|---|
createdAt | DateTime | Creation time of the program schedule. |
startOn | DateTime | Start time of the program schedule. If the program was started with the Now option startOn reflects the time the program started. If the program was started at some date in the future startOn reflects the user's selection. |
stopOn | DateTime | Stop time of the program schedule. A null value in this field represents the Never stop option. |
Retrieving a collection of Engagement Studio Programs follows the conventions described in Version 5 Overview.
Example request:
Example response:
Retrieving a collection of Engagement Studio Programs follows the conventions described in Version 5 Overview.
An encrypted and base64 encoded Engagement Studio Program can be downloaded using the Download Program Structure endpoint. This file holds an Engagement Studio Program structure without specific information from the source (such as object IDs). A downloaded program structure file is required to create an Engagement Studio Program using the Create with File endpoint.
Example request:
Example response:
An Engagement Studio Program POST request must have a JSON body with all required fields specified, as described in the Version 5 Overview. An Engagement Studio Program file obtained from the Download Program Structure endpoint is also required, and must be uploaded to the body of the request.
Example Request:
Example response
The fields in the response body and location header are the same as the fields specified on the example request.
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.
idcreatedAtupdatedAt
Example request:
Example response:
When executing a query for Engagement Studio Programs, use these parameters to filter the results. Specify parameters 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 Engagement Studio Program where ID is equal to the given integer value. |
idList | Returns any Engagement Studio Program where ID is included in the given list of values. |
idGreaterThan | Returns any Engagement Studio Program where ID is greater than the specified value, non-inclusive. |
idGreaterThanOrEqualTo | Returns any Engagement Studio Program where ID is greater than or equal to the specified value. |
idLessThan | Returns any Engagement Studio Program where ID is less than the specified value, non-inclusive. |
idLessThanOrEqualTo | Returns any Engagement Studio Program where ID is less than or equal to the specified value. |
createdAt | Returns any Engagement Studio Program where createdAt is equal to the given datetime value. |
createdAtAfter | Returns any Engagement Studio Program where createdAt is after the given datetime value, non-inclusive. |
createdAtAfterOrEqualTo | Returns any Engagement Studio Program where createdAt is after or equal to the given datetime value. |
createdAtBefore | Returns any Engagement Studio Program where createdAt is before the given datetime value, non-inclusive. |
createdAtBeforeOrEqualTo | Returns any Engagement Studio Program where createdAt is before or equal to the given datetime value. |
updatedAt | Returns any Engagement Studio Program where updatedAt is equal to the given datetime value. |
updatedAtAfter | Returns any Engagement Studio Program where updatedAt is after the given datetime value, non-inclusive. |
updatedAtAfterOrEqualTo | Returns any Engagement Studio Program where updatedAt is after or equal to the given datetime value. |
updatedAtBefore | Returns any Engagement Studio Program where updatedAt is before the given datetime value, non-inclusive. |
updatedAtBeforeOrEqualTo | Returns any Engagement Studio Program 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:
draft: The program has never been run and can be edited.running: The program is currently running and can't be edited.paused: The program isn't running and is eligible for edits (not supported at this time).starting: The program is in the process of starting and can't be edited.scheduled: The program is scheduled to start.