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.

OperationHTTP VerbURL FormatAbility Requirements
ReadGEThttps://pi.pardot.com/api/v5/objects/engagement-studio-programs/<id>?<params>Marketing > Engagement Studio > Engagement Program > View
QueryGEThttps://pi.pardot.com/api/v5/objects/engagement-studio-programs?<params>Marketing > Engagement Studio > Engagement Program > View
Download Program StructureGEThttps://pi.pardot.com/api/v5/objects/engagement-studio-programs/<id>/download-program-structureMarketing > Engagement Studio > Engagement Program > View
Create with FilePOSThttps://pi.pardot.com/api/v5/objects/engagement-studio-programs?<params>Marketing > Engagement Studio > Engagement Program > Create/Edit
FieldTypeDescription
nameStringName of the object for identification in Account Engagement.
FieldTypeDescription
folderIdIntegerID of the folder containing this object. Uses the asset type's uncategorized folder if not specified on create.
FieldTypeDescription
idIntegerID of the object.
statusEnumThe status of the program. See Engagement Studio Program State Enum.
isDeletedBooleanTrue if the object is in the recycle bin in Account Engagement.
salesforceIdStringSalesforceID of the object.
descriptionStringDescription of the object.
businessHoursBusiness Hours RepresentationMap representation of the program's business hours.
prospectsMultipleEntryProspects Multiple Entry RepresentationMap representation of the program's prospects' multiple entry options.
recipientListIdsArrayArray containing the program's Recipient List IDs.
suppressionListIdsArrayArray containing the program's Suppression List IDs.
createdAtDateTimeCreation time of the object.
updatedAtDateTimeLast update time of the object.
createdByIdIntegerID of the user who created this object.
updatedByIdIntegerID of the user who last updated this object.
createdByUserUser object representing the user who created this object. See documentation for User for fields.
updatedByUserUser object representing the user who last updated this object. See documentation for User for fields.
Field NameData TypeDescription
daysArrayArray containing the business days of the week.
startTimeTimeThe start time of the business day.
endTimeTimeThe end time of the business day.
timezoneStringThe timezone of the business hours. See list of all possible timezones
Field NameData TypeDescription
minimumDurationInDaysIntegerThe minimum amount of days before a prospect can reenter the program
maximumEntriesIntegerThe maximum amount of times a prospect can reenter the program. Unlimited entries are represented as null.

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.

  • id
  • createdAt
  • updatedAt

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.

ParameterDescription
idReturns any Engagement Studio Program where ID is equal to the given integer value.
idListReturns any Engagement Studio Program where ID is included in the given list of values.
idGreaterThanReturns any Engagement Studio Program where ID is greater than the specified value, non-inclusive.
idGreaterThanOrEqualToReturns any Engagement Studio Program where ID is greater than or equal to the specified value.
idLessThanReturns any Engagement Studio Program where ID is less than the specified value, non-inclusive.
idLessThanOrEqualToReturns any Engagement Studio Program where ID is less than or equal to the specified value.
createdAtReturns any Engagement Studio Program where createdAt is equal to the given datetime value.
createdAtAfterReturns any Engagement Studio Program where createdAt is after the given datetime value, non-inclusive.
createdAtAfterOrEqualToReturns any Engagement Studio Program where createdAt is after or equal to the given datetime value.
createdAtBeforeReturns any Engagement Studio Program where createdAt is before the given datetime value, non-inclusive.
createdAtBeforeOrEqualToReturns any Engagement Studio Program where createdAt is before or equal to the given datetime value.
updatedAtReturns any Engagement Studio Program where updatedAt is equal to the given datetime value.
updatedAtAfterReturns any Engagement Studio Program where updatedAt is after the given datetime value, non-inclusive.
updatedAtAfterOrEqualToReturns any Engagement Studio Program where updatedAt is after or equal to the given datetime value.
updatedAtBeforeReturns any Engagement Studio Program where updatedAt is before the given datetime value, non-inclusive.
updatedAtBeforeOrEqualToReturns any Engagement Studio Program where updatedAt is before or equal to the given datetime value.
deletedDetermines 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.