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.

Note

Copying Engagement Studio Programs

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.

Note

Supported Operations

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

Fields

Required Editable Fields

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

Optional Editable Fields

Field	Type	Description
`folderId`	Integer	ID of the folder containing this object. Uses the asset type’s uncategorized folder if not specified on create.

Read-Only Fields

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.

Business Hours 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

Prospects Multiple Entry Fields

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`.

Schedule Fields

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.

Read

Retrieving a collection of Engagement Studio Programs follows the conventions described in Version 5 Overview.

Example request:

1GET /api/v5/objects/engagement-studio-programs/50?fields=id,name,status,businessHours,prospectsMultipleEntry,schedule
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example response:

1HTTP/1.1 200 OK
2Content-Type: application/json

1{
2  "values": [
3    {
4      "id": 50,
5      "businessHours": {
6        "days": ["Mon", "Wed", "Fri"],
7        "endTime": "16:00:00",
8        "startTime": "09:00:00",
9        "timezone": "America/New_York"
10      },
11      "name": "ES Program 2",
12      "prospectsMultipleEntry": {
13        "minimumDurationInDays": 5,
14        "maximumEntries": 3
15      },
16      "schedule": {
17        "createdAt": "2024-02-12T10:13:40-08:00",
18        "startOn": "2024-02-13T11:15:00-08:00",
19        "stopOn": null
20      },
21      "status": "draft"
22    }
23  ]
24}

Query

Retrieving a collection of Engagement Studio Programs follows the conventions described in Version 5 Overview.

Download Program Structure

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:

1GET /api/v5/objects/engagement-studio-programs/50/download-program-structure
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example response:

1HTTP/1.1 200 OK
2Content-Type: text
3Content-Disposition: attachment; filename="engagement_studio_program_50_structure.txt"
4Content-Description: Engagement Studio Program Structure
5Content-Transfer-Encoding: text

1oespdZXNfYXBpX29wYXF1ZV9jb3B5eyJ3b3JrZmxvdyI6eyJkZXNjcmlwdGlvbiI6bnVsbCwidHlwZSI6IjQiLCJp
2c19hcmNoaXZlZCI6ZmFsc2UsIm93bmVyX2lkIjpudWxsLCJjcm1faWQiOm51bGwsImFwcF9yZWxlYXNlX3ZlcnNpb
324iOiJyMjEyLjEuMCJ9LCJub2RlcyI6W3siaWQiOiIzMTQ4NTYiLCJuYW1lIjoiQWN0aW9uLkFkZC5Uby5MaXN0Ii
4wibmFtZV9pbmRleCI6IjAiLCJ0eXBlIjoiMiIsInZhbHVlIjpudWxsLCJwYXJhbWV0ZXJzIjpudWxsLCJtYXRjaF9
50eXBlIjpudWxsLCJ0aW1lb3V0IjoiMCIsImNybV9pZCI6bnVsbCwiaXNfYXJjaGl2ZWQiOmZhbHNlfSx7ImlkIjoi
6MzE0ODIwIiwibmFtZSI6IkFjdGlvbi5BZGp1c3QuU2NvcmUiLCJuYW1lX2luZGV4IjoiMCIsInR5cGUiOiIyIiwid
7mFsdWUiOm51bGwsInBhcmFtZXRlcnMiOm51bGwsIm1hdGNoX3R5cGUiOm51bGwsInRpbWVvdXQiOiIwIiwiY3JtX2
8lkIjpudWxsLCJpc19hcmNoaXZlZCI6ZmFsc2V9LHsiaWQiOiIzMTQ4NDEiLCJuYW1lIjoiQWN0aW9uLkFkanVzdC5
9TY29yZSIsIm5hbWVfaW5kZXgiOiIxIiwidHlwZSI6IjIiLCJ2YWx1ZSI6bnVsbCwicGFyYW1ldGVycyI6bnVsbCwi
10bWF0Y2hfdHlwZSI6bnVsbCwidGltZW91dCI6IjAiLCJjcm1faWQiOm51bGwsImlzX2FyY2hpdmVkIjpmYWxzZX0se
11yJpZCI6IjMxNDg1MCIsIm5hbWUiOiJBY3Rpb24uQWRqdXN0LlNjb3JlIiwibmFtZV9pbmRleCI6IjIiLCJ0eXBlIj
12oiMiIsInZhbHVlIjpudWxsLCJwYXJhbWV0ZXJzIjpudWxsLCJtYXRjaF90eXBlIjpudWxsLCJ0aW1lb3V0IjoiMCI
13sImNybV9pZCI6bnVsbCwiaXNfYXJjaGl2ZWQiOmZhbHNlfSx7ImlkIjoiMzE0ODUzIiwibmFtZSI6IkFjdGlvbi5B
14IndvcmtmbG93X25vZGVfaWQiOiIzMTQ4NzQiLCJ0eXBlIjoiNSIsInN1YnR5cGUiOm51bGwsInZhbHVlIjpudWxsL
15CJvYmplY3RfdHlwZSI6ImVtYWlsX3RlbXBsYXRlIiwicGFyYW1ldGVycyI6bnVsbCwic29ydF9vcmRlciI6IjAiLC
16Jpc19hcmNoaXZlZCI6ZmFsc2V9XX0=

Create with File

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:

1POST /api/v5/objects/engagement-studio-programs/?fields=id,name,status,businessHours,prospectsMultipleEntry
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: multipart/form-data; boundary=----boundary-marker
5
6----boundary-marker
7Content-Disposition: form-data; name="file"; filename="engagement_studio_program_1_structure.txt"
8
9<file-data>

1{
2  "name": "Engagement Studio Program API",
3  "folderId": 45
4}

Example response

1HTTP/1.1 200 OK
2Content-Type: application/json
3Location: https://pi.pardot.com/api/v5/objects/engagement-studio-programs/50?fields=id,name,status,businessHours,prospectsMultipleEntry,schedule

1{
2  "values": [
3    {
4      "id": 50,
5      "businessHours": {
6        "days": ["Mon", "Wed", "Fri"],
7        "endTime": "16:00:00",
8        "startTime": "09:00:00",
9        "timezone": "America/New_York"
10      },
11      "name": "ES Program 2",
12      "prospectsMultipleEntry": {
13        "minimumDurationInDays": 5,
14        "maximumEntries": 3
15      },
16      "schedule": {
17        "createdAt": "2024-02-12T10:13:40-08:00",
18        "startOn": "2024-02-13T11:15:00-08:00",
19        "stopOn": null
20      },
21      "status": "draft"
22    }
23  ]
24}

The fields in the response body and location header are the same as the fields specified on the example request.

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/engagement-studio-programs?fields=id,name,folderId&orderBy=id
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example response:

1HTTP/1.1 200 OK
2Content-Type: application/json

1{
2  "values": [
3    {
4      "id": 30,
5      "name": "ES Program 1",
6      "folderId": 1
7    },
8    {
9      "id": 50,
10      "name": "ES Program 2",
11      "folderId": 2
12    },
13    {
14      "id": 75,
15      "name": "ES Program 3",
16      "folderId": 10
17    }
18  ]
19}

Filtering Results

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:

1GET /api/v5/objects/engagement-studio-programs?fields=id,name,status,businessHours,prospectsMultipleEntry&id=50
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example response:

1HTTP/1.1 200 OK
2Content-Type: application/json

1{
2  "values": [
3    {
4      "id": 50,
5      "businessHours": {
6        "days": ["Mon", "Wed", "Fri"],
7        "endTime": "16:00:00",
8        "startTime": "09:00:00",
9        "timezone": "America/New_York"
10      },
11      "name": "ES Program 2",
12      "prospectsMultipleEntry": {
13        "minimumDurationInDays": 5,
14        "maximumEntries": 3
15      },
16      "status": "draft"
17    }
18  ]
19}

Enums

Engagement Studio Program State

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.