marketo_api_quick_start_guide.png

Quick-Start Guide to the API

Tyron_Pretorius
Level 8
Level 8

marketo_api_quick_start_guide.png

 

 

If you are doing any repetitive work within Marketo e.g. bulk merging leads, bulk creating programs etc then you should look into using the API within code scripts or an automation tool such as Zapier to automate these processes.

This post will take you all the way from the docs to making your first requests in Postman to integrating these requests into Zapier actions or scripts in your favorite programming language.

 

What is an API?

Anyone can Google the technical definition of an API and what it does so I won't go into that here. I will instead offer as layman a definition as possible.

 

Basically, an API is a collection of urls (called endpoints) to which you either retrieve information from (GET request) or post information to (POST request). You can learn how to make your first GET and POST requests in Postman below.

 

According to how the APIs are configured they will adhere to certain protocols and be defined as a certain type of API e.g. REST, SOAP. Although Marketo has a SOAP API, it is no longer under active development and their developers are focusing on the REST API moving forward.

 

Marketo also has a JavaScript API but this API is used for enabling features like lead tracking, form data capture, and personalization on your Marketo landing pages or website and cannot be used to interface with leads and assets. Consequently, I will focus on the REST API for the remainder of this post.

 

API Documentation

For anyone looking to do any sort of automation in Marketo, the API documentation will become your bible, allowing you to retrieve information about leads and assets (landing pages, emails, programs) or modify them programmatically.

 

The API landing page has everything you need to get started by showing you how to set up an API user and get the "Client Id" and "Client Secret" needed for authentication.

 

Testing using Postman

Before integrating any call into a script or an automation tool like Zapier, I recommend testing the call out first in the free API testing tool, Postman. This way you can test that you are making the request correctly and you can see what the output response from this request will look like.

 

To get access to my Marketo API Postman collection, which contains 100+ pre-configured requests that you can import into Postman and start using right away then give me a message and I'll send it over 🙂

 

Create an Environment & Variables

The first step in making calls in Postman is to set up an environment and associated environment variables.

 

Environment & Variables in PostmanEnvironment & Variables in Postman

 

 

 

  1. Click on the "Manage Environments" icon to the right of the eye icon
  2. Click "Add" in the pop-up window that appears
  3. Name the environment e.g. "Marketo"
  4. Create 4 variables to contain the base URL, Client Id, Client Secret, and Bearer Token
    1. The values for the base URL, Client Id, and Client Secret can be found from the authentication section in the docs. The base URL should be the same as the "Endpoint" and "Identity" URLs but with the "/rest" or "/identity" removed from the end e.g. base_url = https://xxx-xxx-xxx.mktorest.com

 

Making Your First GET Request

The request that you will use the most whether in Postman, scripts, or Zapier will always be the request to get an access token since this token is required to authenticate all other requests.

  1. Click on "New" in the top left-hand corner of the screen
  2. Select "Request"
  3. Name the request
  4. Select a collection to store the request or use the "Create Collection" option to create a new collection to store all your Marketo requests.
  5. Paste {{base_url}}/identity/oauth/token?grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}} into the URL bar
    1. The request type dropdown is already set to "Get"
    2. The 3 variables we created earlier are brought in using curly brackets
    3. All 3 query parameters specified in the request URL automatically populate the "Params" tab beneath the URL bar
  6. Ensure that your Marketo environment is selected in the environment dropdown so that the request can access the 3 variables above
  7. Switch to the "Tests" tab
  8. Paste the code below into the "Tests" window
    1. This code will take the "access_token" value returned and automatically store it in the "bearer_token" variable

var jsonData = pm.response.json();
pm.environment.set("bearer_token", jsonData.access_token);

  1. Click "Save"
  2. Click "Send"

 

GET request for authorization in PostmanGET request for authorization in Postman

 

Bingo Bango! You have now made your first request. What's more, thanks to the code we pasted in the "Tests" tab we now have the access token stored as a variable that we can use in all other request we make in Postman (see section below). This authorization token only has a lifetime of 3600 seconds so you will need to run this authorization request regularly to get valid tokens.

 

Making Your First POST Request

  1. Click on "New" in the top left-hand corner of the screen
  2. Select "Request"
  3. Name the request
  4. Select your Marketo Collection
  5. Paste {{base_url}}/rest/asset/v1/program/1234.json into the URL bar
    1. Replace "1234" with the program id of a program that you can use for testing
      1. A program id can be extracted from the URL displayed when clicking on a program e.g. https://engage-ab.marketo.com/?munchkinId=xxx-xxx-xxx#/classic/PG1234A1
  6. Ensure that your Marketo environment is selected in the environment dropdown so that the request can access the base_url variable above
  7. Switch to the "Authorization" tab
  8. Set the "Type" to "Bearer Token"
  9. Paste "{{bearer_token}}" into the "Token" field
    1. This bearer_token variable will automatically be populated with the access token from the GET request we made above
  10. Switch to the "Body" tab
  11. Select the "x-www-form-urlencoded" radio button
  12. Set the "Key" to "description" and "Value" to "My First POST Request"
  13. Click "Save"
  14. Click "Send"

POST request to update program description in PostmanPOST request to update program description in Postman

 

 

Et Voila! Check the response in the Postman console to see how the description of the program was updated. The skeptics among us can check the description of the program within their instance to see that it has indeed been updated!

 

Making a request in your Favorite Coding Language

One of the best features of Postman for beginners is its ability to output the code for any request you create in any of 17 languages ranging from C to JavaScript to Python.

  1. Click the "Code" link just under the "Send" button
  2. Select your preferred language and library combination on the left-hand side
  3. Copy the code that appears in the window

 

Python generated code for the program update POST requestPython generated code for the program update POST request

 

 

Now that you have the ability to create requests in your programming language of choice you can now embed these requests in scripts to unlock more advanced interaction with leads and assets in Marketo. Alternatively, you can now use these generated code snippets within Zapier to make requests.

 

As an aside, there is a Marketo API library for Python that will allow you to make requests very easily, however, if you intend to make requests within Zapier then you will not be able to use this library. Zapier currently uses Python version 3.7 and it does not allow you to import custom libraries. Therefore, you will have to follow the steps above to get the code for the request and then follow the steps below to make the request from within Zapier.

 

Making requests in Zapier

As you might have already guessed, Zapier is built entirely on APIs to offer integrations with many different software tools through an easy-to-use drag and drop builder. However, sometimes Zapier will not have an integration with a platform you require or they will not have certain functionality available for an integrated platform.

 

For example, the only trigger available in Zapier for Marketo is the "New Lead" trigger and the only actions available are "Create or Update Lead", "Add Lead to List", and "Find Lead".

 

"New Lead" trigger  in Zapier"New Lead" trigger in Zapier

 

 

 

The 3 available Marketo actions in ZapierThe 3 available Marketo actions in Zapier

 

 

This means if you want any of the other functionality offered through the Marketo API you will have to use the "Code by Zapier" app along with your own custom code in either Python (version 3.7) or Javascript (Node 10.x.x).

 

"Code by Zapier" action"Code by Zapier" action

 

N.B. Before importing any code into the "Code by Zapier" action I recommend testing the code in an online compiler e.g. OnlineGDB for Python, or in a platform such as Pycharm (for Python). Debugging errors within Zapier is not easy but if you use platforms such as these then you can leverage their tools for debugging and then copy and paste the code to Zapier once it is ready.

 

Adhering to API Limits

Once you start incorporating calls into your scripts or Zapier actions it is possible for calls to be made in rapid succession using loops or for calls to be made in parallel using multi-threading or having multiple scripts running at once. In these scenarios, it is important to be aware of the API limits so that your requests do not get stopped for exceeding these limits.

 

50k Daily Quota

If you are importing or exporting large amounts of data into or from your instance, then it is advised to use the Bulk Import and Bulk Extract APIs, which are optimized for uploading or retrieving information and minimizing Calls. If you are integrating Marketo with a business intelligence tool like Domo then you should ensure that this business intelligence tool is using the bulk extract API so it does not exhaust your daily quota.

 

Rate Limit of 100 calls per 20 seconds

When making calls within any sort of loop it is important to use a scheduler e.g. the apscheduler in Python, to throttle the number of requests being made.

 

If you are not concerned with how quickly your script runs then simply implementing a 0.2sec delay at the end of your loop will ensure that you do not exceed 100 calls per 20 seconds.

 

Concurrency Limit of 10 calls

Avoiding the concurrency limit comes down to scheduling and communication between the different scripts you have making requests to your instance.

 

When performance is not a concern, then ensure that there is only one program making requests to your instance at any point in time and that within this program the flow is linear so that the next request will only commence once the previous request has completed.

 

When performance is a concern and you need to have multiple programs running at once or multiple calls being made within a single program in parallel i.e. asynchronous programming, then these concurrent processes will need to communicate with one another and a scheduler library e.g. the apscheduler in Python should be used to ensure that no more than 10 calls are being made at once.

 

What can be automated with the API?

Now that you know where to find the API library and how to use these requests in scripts or Zapier the world is your oyster!

 

To get access to my Marketo API Postman collection, which contains 100+ pre-configured requests that you can import into Postman and start using right away then give me a message and I'll send it over 🙂

 

If you want examples of processes that you can automate using the API take a look at these posts for inspiration:

The content in this blog has been reviewed by the Community Manager to ensure that it is following Marketing Nation Community guidelines. If you have concerns or questions, please reach out to @Jon_Chen or comment down below.

627
0