Overview
The purpose of this article is to outline the steps needed to connect the Integrate Demand Acceleration Platform to post leads (contacts) to Marketo via Marketo’s REST API. It will list what is needed from within Marketo, where to retrieve integration information from Marketo, and how to use this information to create a new integration within the Integrate Demand Acceleration Platform.
This article includes these sections:
- Initial Marketo Set Up
- Gather Required Information from Marketo
- Connect Your Marketo Instance to the Demand Acceleration Platform
- Integrate Template - Connecting to Marketo
Before You Begin
You will need to access your Marketo Admin section (Marketo Admin permission) and your Integrate Demand Acceleration Platform. It is recommended that you are logged into both platforms and have them both open.
Initial Marketo Set Up
To connect the Integrate Demand Acceleration Platform to your instance of Marketo, you will first need to create a new Launchpoint service to use within Marketo. Before you can do this, you will need an API Only Role and API Only User in Marketo that you can use in this new Launchpoint service.
Within your Marketo instance, first create a new API Only Role.
When creating this new role, you will need to select the Access API permissions. Not all of the subcategories are required, but we suggest starting with:
- Read-Write Activity (required)
- Read-Write Activity Metadata (required)
- Read-Write Custom Object (if applicable)
- Read-Write Custom Object Type (if applicable)
- Read-Write Lead (required)
- Any others you think may apply given your Marketo setup
Once created, assign this role to a New API Only User.
You can now create a new Launchpoint service and assign the API Only User you just created to this service.
Gather Required Information from Marketo
Once your Launchpoint service and API Only User are assigned, you’ll need to retrieve the following datapoints from Marketo.
- Client ID
- Client Secret
- REST API Endpoint URL
- REST API Identity URL
- REST API Field Names (and details)
Instructions and details to help you collect these are outlined below.
Client ID & Client Secret
Gather the credentials Client ID and Client Secret that were generated for your newly created custom Launchpoint service. For instructions to find these, see the Credentials for API Access section of the Marketo documentation.
REST API Endpoint & Identity URL
Gather your REST API Endpoint and Identity URLs by navigating to the Marketo Admin > Web Services section.
We have redacted some details from Marketo screenshots for security reasons.
Rest API Field Names & Details
Lastly, gather your REST API Field Names. You can easily export these from the within the Marketo Admin > Database Management > Field Management section by selecting Export Field Names.
In the exported CSV file, from the first column labeled REST API Name, gather the field names of those you want the Integrate Demand Acceleration Platform to post values into
- Helpful Hint: You do not need to include ALL of your Marketo fields in your integration from the Demand Acceleration Platform. You can pick and choose which ones you want to give the Demand Acceleration Platform write-access to.
- Please Note: Common fields include basic contact and company information, and also CRM campaign IDs, source information, Integrate Lead ID, etc.
Also note the following for each field:
- If it is a required field for your Marketo / CRM
- Type of field (string, currency, date, datetime, integer, phone, Boolean, etc.)
- If it is a picklist field, please also note the picklist values associated (common for state, country, industry, etc.)
- Field length requirements (min/max # of characters)
- Any other field validation requirements
Connect Your Marketo Instance to the Demand Acceleration Platform
Now that you have all the required information from Marketo, you can establish your Integrate Demand Acceleration Platform integration to Marketo.
Within the Integrate Demand Acceleration Platform, click the Settings (gear) icon in the top right.
Navigate to the Integration Hub page.
Within the Integration Library section, locate the Marketo (REST) integration tile and click the + symbol to open the configuration modal.
On the Authentication tab, add the Marketo information that you gathered in the first part of this guide – Client ID, Client Secret, Endpoint URL, Identity URL
On the Response Mapping tab, you can modify how Integrate should interpret the response codes Marketo provides the Integrate platform when it delivers a lead.
- Helpful Hint: Most customers leave the default response mapping, unless otherwise needed. Read on for more details if desired.
- By default, all response codes result in the lead continuing to stay in an Accepted state within Integrate unless you have selected Create Only as the action (read the following section for information on actions).
- Updating a response code to Reject will result in the lead updating to a Rejected status upon posting out, removing it from the total accepted lead count. In either case the disposition is reflected within Demand Acceleration Platform.
If you wish to update, click the dropdown in the Status and Disposition columns next to the response you would like to update and make your desired selection.
On the Settings tab, you can name your Marketo integration, select the Action, and add your Marketo API field names (Schema).
- Nick Name – Enter a name for your Marketo integration.
- Helpful Hint: If you will be connecting multiple instances, use a naming convention to help you distinguish them.
- Helpful Hint: If you will be connecting multiple instances, use a naming convention to help you distinguish them.
- Enable Add To Program – Routing using Marketo Add to Program can be turned on at the Source level to determine how leads are routed into your Marketo.
- Action – Decide on the default Action you would like to assign. You can change this on your Source Integrations as well.
What does each action mean?
- Create or Update – Set as default, new leads will be created and leads that already exist in Marketo will be updated.
- Please Note: Almost all Demand Acceleration Platform and Marketo customers use this setting. If you’re thinking about altering this setting, first contact your Integrate Customer Success Manager for additional information and guidance.
- If you already have duplicate records in your Marketo and use this setting, the lead will receive a response code of ‘1007 Multiple leads match the lookup criteria’ and nothing will be updated. If you have many duplicate records, see the Create Duplicates option below.
- Create Only – Only new leads that do not already exist in your Marketo will be created. Leads that already exist will be rejected within the Demand Acceleration Platform.
- Update Only – Only leads that already exist in your Marketo will be updated. New leads will receive a ‘1004 Lead Not Found’ response code and will not post into your Marketo instance.
- Create Duplicate – If a lead already exists in your Marketo, a duplicate record will be created, and net new leads will be created as normal. If you have many duplicate records, this action may be useful.
- Create or Update – Set as default, new leads will be created and leads that already exist in Marketo will be updated.
- Schema – Add your Marketo REST API Field Names that you gathered in the previous section of this guide. You can bulk copy and paste these from Excel, with each field on a new line, into this section.
Once completed, click the Integrate button to save and create your new integration.
You will now see your Marketo Integration in a tile within the System Integrations section at the top of your Integration Hub page.
If changes need to be made, e.g. additional fields need to be added, you can open this modal to add or adjust any of your settings.
To learn to use your new Marketo Integration and configure an integration at the Source level, see the article Setting Up a Source Integration to Marketo.