Giving Hightouch access to Marketo's API requires you to create a Custom Service and API Only User for that service in Marketo.
Even if you already have a Marketo API User, it's best to create one that's solely for the Hightouch service you'll create.
Having a dedicated user for the Hightouch integration lets you more easily track changes from Hightouch syncs.
Before you can create a Custom Service, you need to create a Marketo role with API Access and a user with that role.
None of the default Marketo Roles have API access, so if this is your first API integration in Marketo, you first need to create an API access role.
In Marketo, go to Admin > Users & Roles > Roles and click New Role.
Enter a Role Name (for example, "Hightouch Integration Role") and Description. Then assign all permissions listed in this table to the role:
Sync Type
Necessary permissions
Standard and custom objects
Read-Write Company (for company objects), Read-Write Opportunity (for opportunities), Read-Write Person (for leads), and Read-Write Custom Object and Read-Write Custom Object Type (for any custom objects)
Custom activities
Read-Write Activity, Read-Write Activity Metadata
Static lists
Access Marketing Activities > List Import
Campaign triggers
Read-Write Assets, Activate Campaign
Click Create.
If you try setting up a Marketo destination with an API access role that wasn't assigned all permissions in the table above, the destination setup fails with a 603 - Access denied error.
After creating a role, you need to create an API-Only user.
API-Only users are a special type of user in Marketo, as they are administrated by other users and cannot be used to log in to Marketo.
In Marketo, go to Admin > Users & Roles > Users and click Invite New User.
Enter an email address, first name, and last name for the user. (These don't need to be valid.) Click Next.
Custom Services provide the actual credentials required to authenticate Marketo to Hightouch.
To provision one, follow these instructions:
In Marketo, go to Admin > LaunchPoint and select New Service.
Give your service a descriptive name. From the Service list, select the Custom. Give your service a description, for example, "Hightouch Integration" and select the API Only user you previously created, then click Create.
This adds a new service to your list of LaunchPoint services, and the option to View Details. Click on View Details and save the Client Id and Client Secret for use in Hightouch.
You're now ready to provide Hightouch access to Marketo.
If you created an IP Allowlist in your Marketo settings, make sure to allowlist Hightouch IP addresses so Hightouch can reach your cluster. Refer to our
IP address docs to find the relevant IP addresses for your Hightouch region.
In Hightouch, go to the Destinations overview page and click the Add destination button. Select Marketo and click Continue. You can then authenticate Hightouch to Marketo by entering the following fields:
You can find the Base URL in Admin > Integration > Web Services under REST API.
Only use the part after https:// and before /rest as your base URL, for example, 663-XSQ-200.mktorest.com.
Once you've set up your Marketo destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the Marketo destination you want to sync to.
You can match rows from your model to objects in Marketo on any column in your model and certain fields in Marketo. To avoid duplications or other data issues, it's imperative to choose a column with unique values. Refer to the record matching docs for more information.
The Marketo fields available for record matching depend on the object:
Hightouch lets you sync object fields via field mapping.
You can map data from any of your model columns to an object's default fields.
Ensure your model columns data types match the data types of the fields you want to sync to.
When syncing custom activities, Hightouch treats any records added to your model as new activities and sends them to Marketo when your sync runs.
To sync custom activities, the custom activity type must first be created and approved in Marketo.
You can learn more about creating custom activities in Marketo's docs.
To start, select a custom activity type you've already created in Marketo.
If you don't see it in the dropdown, make sure it's approved in Marketo and then click Refresh in Hightouch.
You can optionally select a column that contains timestamps of when activities occurred. If this field is empty, Marketo uses the time the activity arrives at the server.
You can also map data from any of your model columns to a custom activity's non-primary attributes.
Ensure your model columns data types match the data types of the fields you want to sync to.
You can create a new static list or use an existing one. When creating a new static list, you can optionally enter a name; otherwise, Hightouch defaults to the name of the associated model. To use an existing static list, select the desired static list from the dropdown.
If you're creating a new static list in Marketo, you need to select the folder/program to create the list in. Static lists can only be created in
folders and programs of the following types:
Email Batch Program
Marketing Program
Nurture Program
List
In the Marketo UI, you can tell whether the folder is one of the above types by right clicking the folder in the Marketing Activities sidebar. If the "New local asset"
or "Create list" options are available, then the folder supports static lists.
By default, Hightouch retries all records in a rejected batch. To pinpoint which users are getting rejected with which errors and reduce the number of valid users that get retried, you can enable split retries.
Before you can set up a Hightouch sync to trigger a campaign, you need to have an active trigger campaign with Web Service API as the source in Marketo.
For details, follow the setup instructions below.
If you haven't already, go to Design Studio to draft an email template in your Marketo instance. Before your email template you can use the email template in Hightouch, your draft must be approved.
You can use custom tokens to populate your email template with data from your model.
In the example screenshot above, a custom token makes it possible to dynamically populate the email subject.
Next, you need a Smart Campaign to trigger. Follow these steps if you need to create a new one. Make sure that your campaign belongs to a program.
Open the Smart List tab in the top nav to configure the trigger. Drag and drop Campaign is Requested from the triggers list on the right.
Select that the source isWeb Service API.
Open the Flow tab in the top nav to configure your flow. Drag and drop Send Email from the actions on the right.
Select the email template you want to send.
Open the Schedule tab in the top nav to configure your qualifications. Click on Edit to edit your qualifications.
Hightouch doesn't check if an email has been sent to
a distinct lead before trigger a campaign. For example, if a lead with email janedoe@example.com
appears in two of the queried rows from your model, then Hightouch triggers
an email for each of these rows. Two emails would be sent to janedoe@example.com. If you want to only send
one email per lead, set your qualifications in Marketo to only
once.
Each new row in your model triggers your Marketo Smart Campaign.
That means that Hightouch triggers the campaign for every row in your model on your first sync run, or if you trigger a full resync.
In subsequent sync runs, only new rows in your model's query results trigger the campaign.
To start, select a campaign you've created in Marketo.
Only campaigns triggerable via web service API are listed here.
If you don't see the campaign you want to trigger in the dropdown, make sure it's follows the prerequisites and then click Refresh in Hightouch.
Marketo Smart Campaigns can only be triggered for leads that already exist in your Marketo instance.
To trigger an email for the intended leads, select the model column that contains either the leads' Marketo GUID or Email.
If you use email for your lead matching and your leads aren't
de-duplicated by email, Hightouch uses the latest lead based on the
createdAt timestamp.
Before activating your campaign trigger sync, it's best to test it with with an example lead whose email inbox you have access to.
This lets you inspect the test email.
Click Test from the sync configuration page.
You can manually overwrite columns of a test row.
In the example below, since the sync uses the Email column to match leads, you can manually overwrite the Email field to test lead's email address.
If you're using the Marketo GUID column to match leads, you need to manually overwrite the Marketo GUID field to the test lead's Marketo GUID to send a test email.
Once you've altered the email or Marketo GUID, press Sync as added row. This triggers the campaign for the test lead and sends an email to their inbox.
Check the test lead's email inbox to verify that your configuration sent the intended email with custom tokens populated as expected.
This error means that authentication to Marketo was successful but the account you authenticated with doesn't have sufficient permission to call the Marketo API.
For more information, see Marketo's help article.
This error can happen if you select Update mode when syncing to standard and custom objects. If a record doesn't exist in Marketo yet, you need to select Upsert mode instead, which updates existing records and creates new ones, if needed.
Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.