API

Query

Assets typically have three patterns by which they can be retrieved: by id, by name, and by browsing. By id and by name will both retrieve a single asset for a given parameter, while browsing will return and allow paging through the whole list of assets of that type. Individual types of assets have varying parameters by which they can be filtered, so be sure to look at their individual documents for specifics.

In certain cases the browse endpoint for some asset types will not return child assets, such as the allowable values for a tag, and they must be retrieved individually using either the By Name or By Id endpoint to return the complete set of metadata. Others may have separate endpoints entirely for retrieving dependent objects like Form Fields.

maxReturn – Limits the number of records returned. Defaults to 20 if unset, and has a maximum of 200.

Create and Update

For simple asset types like Folders, Tokens and Files there is typically only a single endpoint for creation, and then an additional endpoint for updating records by ID. Assets are created with a name which is always required, and then any metadata and IDs are returned by the create or update response.

For example, here’s how to create a token:

Request

1

POST/rest/asset/v1/folder/{id}/tokens.json

Body

1

name=April Fools&value=2015-04-01&type=date&folderType=Folder

Response

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

{

"success":true,

"warnings":[],

"errors":[],

"requestId":"e3c2#14e280db5dc",

"result":[

{

"folder":{

"type":"Folder",

"value":416

},

"tokens":[

{

"name":"April Fools",

"type":"date",

"value":"2015-04-01",

"computedUrl":"https://app-abm.marketo.com/#MF1047C3"

}

]

}

]

}

To update a folder you would do this:

Request

1

POST/rest/asset/v1/folder/{id}.json

Body

1

type=Folder&description=Thisisatest(update01)

Response

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

{

"success":true,

"warnings":[],

"errors":[],

"requestId":"c5b2#14e1f3954bf",

"result":[

{

"name":"Learning - deverly",

"description":"This is a test (update 01)",

"createdAt":"2015-03-17T00:17:02Z+0000",

"updatedAt":"2015-06-23T07:02:07Z+0000",

"url":"https://app-abm.marketo.com/#MF1044A1",

"folderId":{

"id":407,

"type":"FOLDER"

},

"folderType":"Marketing Folder",

"parent":{

"id":15,

"type":"FOLDER"

},

"path":"/Marketing Activities/Default/Learning - deverly",

"isArchive":false,

"isSystem":false,

"accessZoneId":1,

"workspace":"Default",

"id":407

}

]

}

Other assets have more complex structures and require updates to additional subsections or child objects, and then ultimately have to undergo approval before they can be put into use. These asset types include Forms, Emails, Email Templates, Landing Pages, and Landing Page templates. These will each have a single endpoint for creating a record, then additional endpoints for updating metadata, content, and content sections.

For example, to create a Landing Page, you’ll need to call its create endpoint with a template ID and then retrieve its content sections, and update each one individually to add content, before approving it so that it can be deployed live.

Complex Create

Landing pages first require creating a Landing Page asset using a parent template. This creates a new landing page containing the default content of the template for each content section.

Approval

Many asset types have an associated draft and approval system, including Emails, Landing Pages, Snippets, Forms, and their corresponding templates. Trying to approve an asset will evaluate it against a specific set of validation rules, and then either set it to an approved state, or return a failure reason. For these types of assets, whenever an update is made to the content of a particular asset the changes are made to a draft of the asset, which does not affect the approved version. This allows changes to content to be safely made without affecting live versions of the asset. The changes can then be applied to the live version by using the approval endpoint. This also clears the draft state of the asset until any additional updates are applied.

The successful approval replaces the previous live version with the updated version.

Discarding drafts is also available through an endpoint for each valid asset type. Using this on an asset which is in an approved with draft state will discard the current draft and any pending changes it has. Using this on an asset that currently has no approved version will do nothing and return an error. Draft-only assets may be deleted, but they may not be discarded.

Assets can also be unapproved if they are in an approved-only state. This will take down any live versions of the asset and returning the asset to a draft-only state while also discarding any associated draft. This action can only be performed on most assets if it is not in use anywhere in Marketo, such as an email being referred to in a Send Email flow step, or a snippet being embedded in an Email.

Request

1

POST/rest/asset/v1/email/{id}/unapprove.json

Response

1

2

3

4

5

6

7

8

9

10

11

{

"success":true,

"warnings":[],

"errors":[],

"requestId":"3514#14a1832b0fa",

"result":[

{

"id":1364

}

]

}

Delete

Assets with approval and draft states, except for forms, may not be deleted while approved, and must be unapproved prior to deletion. Deletions generally can only be performed when an asset is unapproved and out of use and in the case of folders, being empty of assets. One notable exception are programs, which can be deleted along with all of their child contents, so long as the program and its contents are not in use anywhere outside of the bounds of the program.

Latest Blog Posts

Keep up with what's new in the developer world

Important Change to Activity Records in Marketo APIs March 1, 2017 Note: This post will be updated to reflect changes made to activity records returned by the API due to migration to new infrastructure.
With the rollout of Marketo’s next-generation Activity Service beginning in Septmeber, we will be unable to enforce the uniqueness or presence of the integer “id” field in activities, data value changes, or lead deletion ... Read More >

Internet of Things for Marketers with IFTTT and Zapier June 20, 2017 The Internet of Things (IoT) is the inter-networking of connected devices, appliances, wearables, vehicles, etc. with embedded electronics, software, sensors, and network connectivity that enable these objects to collect and exchange data with cloud information systems. These technologies are growing and trending so fast that they will impact how we live, how we work and ... Read More >

Spring 2017 Updates June 16, 2017 In the Spring 2017 release, we are adding the ability to bulk extract lead and activity object data asynchronously, and to manipulate named account lists. See the full list of updates below.
Lead Database APIs
Bulk Extract of Leads
New endpoints to support extraction of leads in bulk. Specify record selection criteria using a variety of options. Details can ... Read More >