Smart Campaigns

Smart Campaigns Endpoint Reference (Asset)

Campaigns Endpoint Reference (Lead)

Marketo offers a set of REST APIs for performing operations on smart campaigns.  These APIs follow the standard interface pattern for asset APIs providing query, create, clone, and delete options.  Additionally, you can manage smart campaign execution by scheduling batch campaigns or requesting trigger campaigns.

Query

Querying smart campaigns follows the standard query types for assets of by idby name, and browsing.

By Id

The Get Smart Campaign by ID endpoint takes a single smart campaign id as a path parameter and returns a single smart campaign record.

For this endpoint, there will always be a single record in the first position of the result array.

By Name

The Get Smart Campaign by Name endpoint takes a single smart campaign name as a parameter and returns a single smart campaign record.

For this endpoint, there will always be a single record in the first position of the result array.

Browse

The Get Smart Campaigns endpoint works like other Asset API browse endpoints and allows several optional query parameters to specify filtering criteria.

The earliestUpdatedAt and latestUpdatedAt parameters accept datetimes that should be in ISO-8601 format (without milliseconds).  If both are set, then earliestUpdatedAt must preceed latestUpdatedAt.

The folder parameter specifies the parent folder to browse under.  The format is JSON block containing id and type attributes.

The maxReturn parameter is an integer that specifies the maximum number of entries to return.  Default is 20.  Maximum is 200.

The offset parameter is an integer that specifies where to begin retrieving entries.  Can be used on conjunction with maxReturn.  Default is 0.

The isActive parameter is a boolean that specifies to return only active Trigger campaigns.

For this endpoint, there will be one or more records in the result array.

Create

The Create Smart Campaign endpoint is executed with an application/x-www-form-urlencoded POST with two required parameters.  The name parameter specifies the name of the smart campaign to create.   The folder parameter specifies the parent folder where the smart campaign is created.  The format is JSON block containing id and type attributes.

Optionally, you may describe the smart campaign using the description parameter (maximum 2,000 characters).

Update

The Update Smart Campaign endpoint is executed with an application/x-www-form-urlencoded POST.  It takes a single smart campaign id as a path parameter.  You can use the name parameter to update the name of the smart campaign, or the description parameter to update the description of the smart campaign.

Clone

The Clone Smart Campaign endpoint is executed with an application/x-www-form-urlencoded POST with three required parameters.  It takes an id path parameter that specifies the smart campaign to clone, a name parameter that specifies the name of new smart campaign, and a folder parameter to specify the parent folder where the new smart campaign is created.  The format is JSON block containing id and type attributes.

Optionally, you may describe the smart campaign using the description parameter (maximum 2,000 characters).

Delete

The Delete Smart Campaign endpoint takes a single smart campaign id as a path parameter.

Batch

Batch smart campaigns launch at a specific time and affect a specific set of leads all at once.

Schedule

Use the Schedule Campaign endpoint to schedule a batch campaign to run either immediately or at a future date.  The campaign id is a required path parameter.  Optional parameters are tokens, runAt, and cloneToProgram which are passed in the request body as application/json.

The tokens array parameter is an array of My Tokens which override existing program tokens.  After the campaign runs, the tokens are discarded.  Each token array item contains name/value pairs.  The name of the token must be formatted as “{{my.name}}”.

The runAt datetime parameter specifies when to run the campaign.  If not specified, the campaign will be run 5 minutes after the endpoint has been called.  The datetime value cannot be more than 2 years into the future.

Campaigns scheduled via this API will always wait a minimum of 5 minutes before running.

The cloneToProgram string parameter contains the name of a resulting program.  When set, this causes the campaign, parent program, and all of its assets to be created with the resulting new name. The parent program will be cloned and the newly created campaign will be scheduled. The resulting program is created underneath the parent. Programs with snippets, push notifications, in-app messages, static lists, reports, and social assets may not be cloned in this way.  When used, this endpoint is limited to 20 calls per day.  The clone program endpoint is the recommended alternative.

Trigger

Trigger smart campaigns affect one person at a time based on a triggered event.

Request

Use the Request Campaign endpoint to pass a set of leads to a trigger campaign to run through the campaign’s flow.  The campaign must have a “Campaign is Requested” trigger with “Web Service API” as the source.

This endpoint requires a campaign id as a path parameter, and a leads integer array parameter containing lead ids .  A maximum of 100 leads are allowed per call.

Optionally, the tokens array parameter can be used to override My Tokens local to the campaign’s parent program. tokens will accept a maximum of 100 tokens.  Each tokens array item contains a name/value pair.  The name of the token must be formatted as “{{my.name}}”.  Note that if you use Add a System Token as a Link in an Email approach to add the “viewAsWebpageLink” system token, you cannot override it using tokens.  Instead use Add a View as Web Page Link to an Email approach which allows you to override “viewAsWebPageLink” using tokens.

The leads and tokens parameters are passed in the request body as application/json.

Activate

The Activate Smart Campaign endpoint is straightforward.  An id path parameter is required.  For activation to succeed, the following must be true for the campaign:

  • Must be deactivated
  • Must have at least one trigger, and one flow step
  • Must have error free triggers, filters, and flow steps

Deactivate

The Deactivate Smart Campaign is straightforward.  An id path parameter is required.  For deactivation to succeed, the campaign must be activated.