Programs

Programs Endpoint Reference

Programs are a core organizational component of Marketo Marketing Activities.  They can be a parent to most types of assets, and allow for tracking of membership and success of leads within the context of individual marketing initiatives.  Programs can be parents to all type of records except for LP and Email Templates, and Files.

Program Types

There are five core types of programs within Marketo:

  • Default
  • Event
  • Event with Webinar
  • Engagement
  • Email

Engagement programs may be parents to each other type of program, while Default, Event and Event with Webinar may only be parents to Email programs.

Programs will always have a channel, and will derive the possible set up Program Member Statuses from the channel which they were created with, which can be retrieved with the Get Channels API.  A program may also have a set of associated tags.  Tags are customizable fields which can be configured to be optional or required for any given type of program, which will have a value selected from a list configured in Marketo Admin.

Query

Programs follow the standard pattern for asset queries with an additional option to query by tag type and values.  Available tags and values can be retrieved with Get Tag Types.

By Id

The Program Id can be obtained from the URL of the program in the UI, where the URL will resemble https://app-***.marketo.com/#PG1001A1. In this URL, the id is 1001, it will always be between the first set of letters in the URL and the second set of letters.

By Name

Browse

When browsing for programs, there is an optional status filter.  This filter only applies to Engagement and Email programs.  The possible values are “on” and “off” for Engagement programs, and “unlocked” for Email programs. There is also an optional integer maxReturn parameter that controls the number of programs to return (maximum is 200, default is 20), and an optional integer offset parameter used for paging results (default is 0).

By Date Range

The earliestUpdatedAt and latestUpdated at parameters to our Get Programs endpoint allow you to set low and high datetime watermarks for returning programs created or updated within the given range.

By Tag Type

There are two required parameters, tagType which is the type of tag to filter on, and tagValue which is the tag value to filter on.  There is an optional integer maxReturn parameter that controls the number of programs to return (maximum is 200, default is 20), and an optional integer offset parameter used for paging results (default is 0).  Results are returned in random order.

Create and Update

Creating and updating programs follows the standard asset pattern and has folder, name, type and channel as required parameters, with description, costs and tags being optional.  Channel and type may only be set at program creation.  Only description, name, tags and costs may be updated after creation, with an additional costsDestructiveUpdate parameter allowed.  Passing costsDestructiveUpdate as true will cause all existing costs to be cleared and replaced with any costs included in the call.  Note that tags may be required for some program types in some subscriptions, but this is configuration-dependent and should first be checked with Get Tags to see if there are instance-specific requirements.

When creating or updating an Email Program, a startDate and endDate may also be passed.

Create

Update

Approval

Email Programs may be approved or unapproved remotely, which will cause the program to run at the given startDate and conclude at the given endDate.  Both of these must be set to approve the program, as well as having a valid and approved email and smart list configured via the UI.

Approve

Unapprove

Clone

Cloning programs follows the standard asset pattern the new name and folder as required parameters and an optional description.  The name parameter must be globally unique.  The folder parameter is the parent folder.  The folder parameter “type” attribute must be “Folder”, and the target folder must be in same workspace as program that is being cloned.

Note: Programs containing certain types of assets may not be cloned via this API, including Static Lists, Snippets, Push Notifications, In-App Messages and Social Assets

Delete Program

Deleting programs follows the standard asset deletion pattern.  Programs containing static lists, reports, landing pages with embedded social buttons, or social buttons, or programs of Push Notification and In-App Message cannot be deleted through this API.