Campaigns

Smart Campaigns Endpoint Reference (Asset)

Campaigns Endpoint Reference (Lead)

Marketo’s Campaign REST APIs provide basic capabilities to manage Smart Campaign execution, and query Smart Campaign metadata.  This includes scheduling batch campaigns, and requesting/activating/deactivating trigger campaigns.

Smart Campaign Query

Querying smart campaigns follows the standard query types for assets.  Query “by name” can be accomplished by using the browse endpoint.

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.

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.

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

Campaign Query

Note that the Campaign Query endpoints in this section have been deprecated. These endpoints are not recommended for new development. If you are currently using, they will continue to function normally but you should transition to the latest Smart Campaign Query endpoints at your earliest convenience.

Querying campaigns follows the standard query types for assets.  Query “by name” can be accomplished by using the browse endpoint.

By Id [Deprecated]

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

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

Browse [Deprecated]

The Get Campaigns endpoint works like other Asset API browse endpoints, and allows optional filtering on several criteria: id, name, programName, workspaceName, isTriggerable.

You may use a comma-separated list of values for id, name, programName, and workspaceName parameters.  For lengthy comma-separated lists (exceeding 8KB), you can place the list in the request body and submit a POST request with _method=GET as a query parameter.  See Long URIs for an example of this.

You may set isTriggerable boolean parameter to true to return only triggerable campaigns.  A triggerable campaign is defined as an active campaign that has a Campaign is Requested trigger whose source is Web Service API.

You may set the batchSize integer parameter to control the number of results that are returned (default and Maximum is 300).  If the result set exceeds the batchSize, a nextPageToken attribute is returned in the response body to facilitate paging.  See Position-Based Paging Tokens for more detail.

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

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.

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.  Each token array item contains name/value pairs.  The name of the token must be formatted as “{{my.name}}”.

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.