Folders

Folders Endpoint Reference

Folders are the core organizational asset in Marketo, and every other type of asset has at least one folder as a parent.  This parent folder may be either a Folder which is purely organizational, or a Program, which has a functional relationship to other asset types and can also be the parent of other assets.  Folders can be created, queried, updated and deleted through the API, and also allow a list of their contents to be retrieved.  Note that, though Programs can be returned through querying the Folders API, creating, updating, and deleting programs must be performed through the Programs API.

Query

Querying folders follows the standard query types for assets of by id, by name, and browsing.

By Id

The type parameter is required and must be one of “Folder” or “Program.”  The type will dictate whether the lookup to the folder is done against a Folder ID or a Program ID.  For this endpoint, only a single record will be returned in the result Array.  Note the folderType parameter in the response.  This can indicate many different types of folders.  Marketo Activities folders will have either a type of Marketing Folder or Program, which can contain many different types of assets, while Design Studio folders will have a type corresponding to the asset type which they can hold.  For example, a folder with folderType of “Email” may contain only Emails, or other subfolders, which might have a folderType of Email or Email Template.  Types may include:

  • Email
  • Email Template
  • Landing Page
  • Landing Page Template
  • Snippet
  • File

By Name

Querying by name is also allowed.  The query by name endpoint has name as the only required parameter.  Name performs an exact string match against the name field of folders in the instance, and returns results for each folder matching that name.  It also has the optional query parameters of “type” which can be Folder or Program, “root” the id of the folder to search through, or “workspace” the name of the workspace to search in.  If the root parameter is set, the type parameter must also be set.

When searching by name, it is important to note that both Marketing Activities and Design Studio are their own root folders, so they can be retrieved by name, and used to traverse the rest of the folder hierarchy in a destination instance.

Browse

Folders can also be retrieved in bulk.  The “root” parameter can be used to specify the parent folder under which the query will be performed and is formatted as a JSON object embedded as the value for the query parameter.  root has two members:

  1. id – The id of the folder or program.
  2. type – Either Folder or Program, depending of the type of the root folder to browser.

If the root folder is not known, or the intent is to retrieve all folders in a given area, the root can be specified as the “Marketing Activities”, “Design Studio”, or “Lead Database” areas.  The ids for each of these can be retrieved through the Get Folder By Name API, and specifying the name of the desired area.

Like other bulk asset retrieval endpoints, offset and maxReturn are optional parameters for paging.   Other optional parameters are:

workSpace – The name of the workspace to filter to.

maxDepth – The maximum number of levels to traverse in the folder hierarchy.  If set to 0, only the folder specified in root is returned.  If not specified, the default value is 2.

Response Structure

Much of the folder response structure is self-explanatory, but a few fields are worth noting individually.  The folderId and parent fields are JSON objects which include the explicit id and type of the folder itself.  This type is the one which is used in queries, root and parent parameters by the API to ensure proper delineation between Folder and Program types of folders.  folderType reflects the usage of the folder, which may be one of “Marketing Folder,” “Program,” “Email,” “Email Template,” Landing Page,” Landing Page Template,” “Snippet,” or “File.”  The types Marketing Folder and Program indicate that they exist in Marketing Activities and can contain multiple types of assets, while the other types indicate that they may contain only that type of asset, subfolders, and the template version of that type, if applicable.

The path of a folder shows its hierarchy in the folder tree, similar to a Unix-style path.  The first entry in the path will always be Marketing Activities or Design Studio.  If the target instance has workspaces, then the second entry in the path will be the name of the owning workspace.  The url field shows the explicit URL of the asset in the designated instance.  This is not a universal link, and must be authenticated as a user to work properly.  isSystem indicates whether or not the folder is a system folder.  If this is set to true then the folder itself is read-only, though folders can be created as children of it.

Create and Update

Creating folders is simple and is executed with an application/x-www-form-urlencoded POST that has two required parameters, “name,” a string, and “parent,” the parent to create the new folder in, which is an embedded JSON object with two members, id, and type, either Folder or Program, depending on the type of the target folder.  Optionally “description,” a string, can also be included and may be up to 2000 characters.

Updates to folders are made through a separate endpoint, and description, name, and “isArchive” are optional parameters for update.  If isArchive is changed by an update, this will result in the folder being archived, if changed to true, or unarchived, if changed to false, in the Marketo UI.  Programs cannot be updated with this API.

Delete

Deletions can be made against single folders if they are empty, meaning that they contain no assets or subfolders.  If a folder is of type Program, or has the isSystem field set to true, it cannot be deleted with this API.