Request Campaign Endpoint and Associated Hidden Caveat
Marketo’s Request Campaign endpoint facilitates the triggering of active smart campaigns for specified people via API. I find this endpoint very versatile and have used it plenty of times, especially in multi-platform architectures, to trigger a flow in Marketo as a result of something happening in other related platforms. However, there's a lesser-known aspect to this endpoint that can make or break your campaign-triggering process. In this post, let’s have a look at this endpoint and then delve deeper into this hidden caveat in detail!
The API Endpoint: Triggering Smart Campaigns
Marketo's Request Campaign endpoint requires two primary parameters:
Campaign ID (path parameter): The unique identifier of the smart campaign you wish to trigger.
Leads (an integer array parameter included in the payload): An array of lead IDs for the individuals you want to target with the campaign.
Additionally, there's an optional parameter:
Tokens (array parameter included in the payload): This parameter is used to override custom My Tokens specific to the campaign's parent program. Each item in the tokens array contains a name/value pair, where the name of the token follows the usual custom my token format: "{{my.name}}".
A sample JSON request body is below:
The Hidden Caveat: No Nested Programs Allowed
Now comes the lesser-known aspect that can catch users off guard. When triggering a campaign using the REST API and specifying one or more tokens, the smart campaign being triggered must not be housed within a nested program (like the one in the snapshot below)
The parent program of the smart campaign must be directly under a campaign folder. Attempting to trigger campaigns residing in nested programs using the API with custom token values in the payload will result in a "System Error (error code 611)" (see the response below). This little caveat is important to note, as it ensures that your campaign structure aligns with the technical requirements of the API.
Interestingly, Marketo's API call doesn't return an error when the "tokens" array parameter is sent empty in the payload. In other words, if you don't intend to override any tokens, you can still trigger a campaign housed in a nested program successfully without encountering issues.
TL;DR: Marketo's API lets you trigger smart campaigns with personalized content for specific individuals. It requires a campaign ID, lead IDs, and optional token values to override. But be cautious: triggered campaigns can't be in nested programs, only under a campaign folder. If you don't want to override any custom tokens, you can leave the "tokens" array empty in the API call, and interestingly, you’d not encounter the system error in this case even if your campaign is housed in a nested program.