Help Center

Menu

Working with Marketo

Get lead

The get lead process refers to the retrieving of lead data from Marketo.

For Matrix to retrieve data, a Marketo bridge must be created and the Marketo settings configured. Read the Marketo bridge documentation for more information.

The Get lead API can be enabled in the Get lead API settings section of the Marketo bridge.

The following example code will retrieve the lead data of the current user and dump this data to the JS console.

This example assumes that the jquery JavaScript library is available in the code and that the Marketo cookie is already set for the current user. Read the Marketo cookie section for more information.

If a Marketo cookie is not available, the email attribute must be provided as the lead key. Read the Verifying an email address section for more information.

<script>
$.get("./?a=1234?action=getLead", function(data){
  console.log(data);
});
//Note: 1234 is the asset ID of the Marketo Bridge asset.
</script>

The allowed attributes setting on the Marketo bridge allows you to specify the attributes to retrieve with the Get lead API. This is useful if you only want to retrieve specific lead data from a user rather than all associated data.

If no cache is required, an extra nocache URL parameter can be added to the code, like so:

<script>
$.get("./?a=1234?action=getLead&nocache", function(data){
  console.log(data);
});
</script>
The Get lead API has a default daily limit of 10,000 requests, imposed by Marketo. This daily limit can be extended to 10,000 unique user sessions with the use of default caching.

Get lead global keywords

As an alternative to the Get lead API, lead data can also be retrieved from Marketo using global keyword replacements.

The following keywords are available for retrieving lead data:

%globals_marketo_lead:1234%

Will output the current user’s lead data in a JSON array format.

%globals_marketo_lead_id:1234%

Will output the lead ID.

%globals_marketo_lead_email:1234%

Will output the lead email.

%globals_marketo_lead_attribute_x:1234%

Will output the attribute as specified (for example, firstname). Where 1234 is the asset ID of the Marketo bridge.

If no cache is required:

  • %globals_marketo_lead_nocache_id:1234%

  • %globals_marketo_lead_nocache_email:1234%

  • %globals_marketo_lead_nocache_attribute_x:1234%

The output of these global keywords will be sanitized by escaping special characters to prevent basic cross-site scripting. You may, however, need to undertake further steps, such as using keyword modifiers, to ensure the usage of these keywords is secure.

Get lead caching

By default, lead data retrieved through the Get lead API or the associated global keyword replacements is cached for a user’s session. This ensures that multiple API calls or keywords will print lead data efficiently. A sync lead call, through either the Sync lead API or the associated form submission action, will recache the lead data for the current user. Similarly, a nocache Get lead API call, or global keyword will also recache this lead data.

If a shorter caching time is required, it can be specified in the lead caching setting on the Details screen of the Marketo bridge.

Sync lead

Sync lead refers to the synching of collected user data to a Marketo service.

To push data to Marketo, a Marketo bridge must be created and the Marketo settings configured. Read the Marketo bridge documentation for more information.

The Sync lead API can be enabled in the Sync lead API settings section of the Marketo bridge.

The following example code will sync lead to Marketo using the Sync lead API, specifying 'firstname' and 'lastname' attributes.

This example assumes that the jquery JavaScript library is available in the code and that the Marketo cookie is already set for the current user. Read the Marketo cookie section for more information. 
<script type="text/javascript">
$.post("https://matrix.squiz.net/releases/archived-releases/5.1/5.1.13.1?action=syncLead",{"FirstName" : "Test", "LastName" : "User"}, function( data ) {
console.log(data); }, 'json');
</script>
1234 is the asset ID of the Marketo bridge asset. The Sync lead API only accepts post requests.

If an 'email' attribute is required to be synced to Marketo, the email must be verified for the session or a trusted email source specified in the Marketo bridge.

The Allowed attributes setting on the Marketo bridge allows you to specify the attributes to sync with the Sync lead API.

Alternatively, you can sync lead using the Marketo sync lead submission action on a custom form page. Read the Custom form documentation for more information.

The Sync lead API and the associated form submission action have a default daily limit of 10,000 requests imposed by Marketo. The Munchkin API is a recommended alternative for larger-scale sites with greater tracking needs.

Munchkin API

Marketo’s Munchkin API is available as an alternative sync lead process, helpful when dealing with large-scale activity tracking.

To push data to Marketo, a Marketo bridge must be created and the Marketo settings configured. Read the Marketo bridge documentation for more information.

The Munchkin API can be configured in the Munchkin API settings section of the Marketo bridge. A trusted email source must be identified in these settings, for example, %globals_user_attribute_email%.

Once you have finished configuring the settings of the Munchkin API, you can use the global keyword %globals_Marketo_munchkin_init:X% to print the initialization code for the Munchkin API call, where X is the asset ID of the Marketo bridge.

The Munchkin API requires an email attribute to be specified for every associate lead call; this email address will be used to generate a hash to pass along with the API call. As a result, a Munchkin email source must be configured in the Munchkin API settings section of the Marketo bridge.

The Munchkin API has no daily request limit, unlike the Sync lead API, which has a request limit of 10,000. This means that it is ideal for large-scale sites with greater tracking needs. However, unlike the Sync lead API, the Munchkin API does not immediately update the lead data in the Marketo database; this could take up to a day after the request is made.

Due to both these strengths and limitations, it is advised that Matrix’s Sync lead API and Marketo sync lead submission action be used when dealing with personal sites with smaller tracking requirements. However, if frequent lead syncs and greater user activity tracking are necessary, the Munchkin API may be better suited for your needs.

Marketo uses a cookie value set by its Munchkin JavaScript library to identify individual users on the domain of your site. The cookie, which sets to a user’s browser, lasts up to two years and is automatically renewed each time the user visits a page.

The Marketo cookie has the name _mkto_trk and a value in the following format:

id:425-NAK-xxx&token:_mch-squiz.net.au-138123456789-12345

This cookie is automatically set by the tracking code on the page if it has not been previously set. More information on the Munchkin tracking code can be found on the Marketo developers site.

The initialization code to set the Marketo cookie can be found in the Munchkin API settings section of the Marketo bridge. Once you have configured the Munchkin API, you can use the global keyword %globals_Marketo_Munchkin_init:X% to print the initialization code for the Munchkin API call, where X is the asset ID of the Marketo bridge.

Both the sync lead and get lead processes require a lead key to be provided to Marketo to identify the user against which to perform the action. The Marketo cookie is simple to implement and safe to use, making it a recommended lead key.

To use the Marketo cookie as the lead key, ensure that the cookie is set for the user before the Marketo bridge performs any data syncing or retrieving. Matrix will automatically use the Marketo cookie for any Marketo integration actions.

Verifying an email address

If a user’s email is being used to sync with Marketo or used as the lead key to retrieve data, it is essential to ensure that the email is verified or from a trusted email source.

To verify a user’s email address, create a send email form submission action or trigger action and configure it to send an email to the user. In the content of the email, provide the user with a link to verify their email address. This link should have a URL parameter, as follows:

?SQ_ACTION=verify_email&email_verification_token=%email_verification_token%

The email_verification_token parameter will be replaced with a unique token. When the user clicks the link in this email, their email address will be verified for the session.

The verified email address can be printed using the following global keyword replacement:

%globals_verified_email%
A verified email is only temporarily stored in the session. If permanent storage is required, a trigger action can be configured to set this value in the user’s metadata.

Once a user’s email is verified, Matrix will automatically detect it when calling the sync lead and get lead actions, and a Marketo cookie will not be required to be set.

Alternatively, a trusted email source can be specified when configuring the sync lead and Get lead APIs on the Details screen of the Marketo bridge. This will provide an additional email address source if a verified email is not available.

For example, using the %globals_user_attribute_email% keyword will use the email attribute of the user as the lead key for the sync lead and get lead processes.