This guide is meant to walk you and your IT/infosec team through setting up your Marketo instance to have the right permissions to have Insentric work—while keeping your data and systems safe. For Insentric to operate, it needs a dedicated API user created inside Marketo. Note that Marketo does not charge you for having an API user, and it does not count toward your instance's overall user limit.

Creating an "Insentric API" role in Marketo

To ensure that Insentric only uses the permissions it requires, we encourage you to set up a dedicated role just for Insentric as opposed to other API users with varying levels of permissions.

1. Log in to your Marketo instance with an administrator access account, then visit Admin → Users & Roles. Click the Roles tab on the screen to bring up all roles listed in your Marketo instance. Your screen should look similar to the following:
   
   


2. Click the New Role button in the top-left corner. Create a new role with the following:

• Role Name: Insentric API
• Description: Permission set for read-only access to Marketo
• Permissions:
  • Access API → Approve Assets (used by Insentric for appending tracking links to emails)
  • Access API → Read-Only Activity (used to parse record behaviors)
  • Access API → Read-Only Activity Metadata (used if custom activities are on instance)
  • Access API → Read-Only Campaign (used to calculate certain behaviors, such as emails being sent multiple times from the same Smart Campaign)
  • Access API → Read-Only Company (used to parse company-level data in Insentric reporting)
  • Access API → Read-Only Custom Object (used if custom objects are on instance)
  • Access API → Read-Only Custom Object Type (used if custom objects are on instance)
  • Access API → Read-Only Lead (used to read records)
  • Access API → Read-Only Opportunity (used to read opportunity data)
  • Access API → Read-Only Salesperson (used to parse data around CRM users, especially opportunities)
  • Access API → Read-Only Platform Insight Metrics (used to control data rate limits and ensure compatibility with other items using the Marketo API)
  • Access API → Read-Write Assets (used by Insentric for appending tracking links to email)

  Creating an "Insentric API" user in Marketo

  1. Now that the Insentric role has been created, we'll need to create a dedicated user and assign that user the role. Click the Users tab in the top-left area to go back to the main User area. From there, click Invite New User. You should see a modal window appear similar to the following:
     
     
  2. For Step 1: Info, you'll need to supply an email, first name, and last name for your API user. We generally recommend using an overall naming schema for managing your Marketo API users; for example, having two users with [email protected] and [email protected] shows all API users sequentially.
     
     That said, we recommend the following setup:
      
     • Email: [email protected] (where "yourdomain.tld" is your company's email domain)
     • First Name: Insentric
     • Last Name: API User
     • Reason: Used to interface with Insentric software
     • Access Expires: Never
  3. For Step 2: Permissions, select the "Insentric API" role you created previously. If your Marketo instance has multiple workspaces, we strongly suggest that your API user have permission to all workspaces. After this, click the "API Only": checkbox below. The result should look similar to this:
     
     
  
  
  4. For Step 3: Message, you should see a message stating "An invitation is not required for API only." Click Send.

  Retrieving Munchkin ID

  The next step you'll want to take is to record your Marketo Munchkin ID. You can access this data by visiting Admin → Munchkin inside Marketo. This ID will be listed as "Munchkin Account ID" in a format similar to 123-ABC-456. This is the main identifier of your instance, so be sure to write this down; we'll be using it later.

• 
  
  
   

  Understanding Marketo API Usage and Calculating for Insentric Usage

  To set up Insentric, you'll want to account for any existing API processes you currently have inside Marketo. This helps ensure Insentric doesn't inadvertently cause problems by using too many API calls for your company's needs. To establish the proper number of calls, you'll need to look in Marketo's Admin section to understand current use. You can do this by visiting Admin → Integration → Web Services. You should see a screen similar to the following:
   

  

  
  Most Marketo customers will have a Daily Request Limit of 50,000 calls and a Purchased Daily Capacity Limit of 500MB. If your instance was provisioned before 2021, you may only have 10,000 API calls available to your instance. If this is the case, you can put in a ticket with Marketo Support to increase your limit to 50,000 calls without charge.

  Measuring API Requests to Calculate Daily Limit

  Note that both "Requests in the Last 7 Days" and "Capacity Used in the Last 7 Days" are cumulative; for example, in this screenshot, this instance has used 88,922 calls over a week. You can better understand what uses those calls and daily fluctuations in numbers by clicking the linked figure next to Requests. This will bring up a modal window similar to the following:
   

  

  
  This example Marketo instance already uses three API users for various items: Improvado, Vidyard and ZoomInfo. When we look at the daily Total at the bottom, we see that the number fluctuates between roughly 10,000 and 15,000. This sort of fluctuation is common, so we recommend adding an additional 20% overage to the largest number you see to figure out what API calls you should reserve for other processes.
  
  Therefore, in this case, we'd take the highest number (14,152), round it up to the next large value (15,000), and then add a 20% buffer, bringing us to 18,000 daily calls used by this instance. Please write this number down; we'll need it soon!

  Measuring Bulk API Usage to Calculate Daily Limit

  Much like API Requests, Bulk Export API Capacity is shown over the past seven days rather than looking at data per day. Clicking on the Capacity Used number will bring up detailed information. This example enterprise instance has purchased additional bulk API capacity, so their daily limit is 7500MB/7.5GB.
   

  
  

  

  
  We can see here that this company fluctuates pretty wildly, sometimes using as little as 48MB and sometimes using 2500MB/2.5GB on a given day. Again, to account for this fluctuation, we'd pick the upper number(2437.35), round up to 2500, then add a 20% supplement—which would bring us to 3000MB/3GB a day in reserved use.

  This means that we'll set Insentric's initial limits for this instance to be:

  API Requests: 100,000 - 18,000 = 82,000 maximum calls by Insentric

  Bulk Export API: 7.5GB - 3GB = 4.5GB
   

  Note that this is only the initial setup and absolute maximums that Insentric can use. After collecting initial historical data, you should be able to gauge Insentric's daily usage more accurately within seven days of it running. You can modify your limits and thresholds anytime by logging into Insentric and adjusting your rates.

  Creating a Launchpoint Connector

  Now that we have our user, role, Munchkin ID, and know your API limits, let's take the final step to set up configuration on Marketo's end. Visit Admin→Launchpoint to see what Installed Services your Marketo instance has. Once the page loads, click New→New Service. This will open a modal window. Set your Display Name as Insentric and Services as Custom. This should generate a screen similar to the following:
  
  

  
  Under Description, place any text you would like to have to explain the service. Do note that the text you put in the Description is not shown anywhere else in Marketo's UI as of December 2023.

  For API Only User, you should be able to select the user you created in the first step, then click Create. This sets up a dedicated connection that Insentric can use and that you can monitor to see performance. Click the "View Details" link next to Insentric to use this connection. You should see a modal window pop up similar to this:
  
  

   

  Copy the Client ID and Client Secret down, as we'll use this later.

  Recap

  To recap, after completing this process, you should have the following information:

  • Munchkin ID
  • Insentric Client ID
  • Insentric Client Secret
  • Daily API Request limit
  • Daily Bulk API Export daily capacity
     

  Once you have these values, you'll head to Insentric to configure your instance.