Marketo API and Recommended Best Practices

Darshil_Shah1 · ‎04-24-2022

First things first, what is an API?

API stands for Application Programming Interface, which is a set of definitions for building and integrating applications. API uses the standardized method of transferring data that lets you connect and facilitate data transfers between two platforms even though they are built on completely different platforms / tech-stack / architecture. APIs essentially serve as a layer of abstraction for the programmatic access of the data present on the back-end.

Marketo APIs

Marketo exposes its REST (Representational State Transfer), SOAP (Simple Object Access Protocol) APIs (Application Programming Interfaces) to allow the remote execution of many of its capabilities. Marketo also has a rich library of JavaScript APIs to perform actions / get data on the client side (more about Marketo's client side JavaScript APIs in another blog, we'll focus on REST/SOAP APIs in this one). Apart from being able to help integrate third party systems with the Marketo, APIs can also be a blessing for pulling off a large change management exercise / use-case that requires you to repeat the same task over and over again across a wide range of Marketo assets which could be easily finger cramping from all the redundant clicks, mundane, time-consuming, and error prone when done via Marketo UI. I will try to summarize about Marketo APIs and some of the best practices related to it while using them to ensure that you get the best out of Marketo APIs.

Marketo REST API

Marketo’s REST endpoints conform to the constraints of the REST architectural style and allow for interaction with the RESTful web services. Wherever possible, it is advised to use the REST APIs instead of SOAP APIs as they are more secure, more efficient and support more data formats than the latter. Marketo is actively enhancing the existing and adding more REST API endpoints. Following are the major categories of the REST APIs exposed by Marketo -

Marketo SOAP API

The Marketo SOAP API allows for the creation, retrieval and removal of entities and data stored within Marketo using the SOAP methods. Marketo has already phased out the SOAP API, though existing SOAP API endpoints are still working. All the future development/enhancement would be centered on the REST APIs, and hence it is advised to use the REST APIs over the SOAP APIs. The key SOAP API categories are listed below.

Custom Object SOAP API
Activities
Lead APIs
Asset APIs such as Static List, Programs and Campaigns

Marketo API Limits

Marketo has reinforced below mentioned limits to its API usage -

Daily Quota: Marketo subscriptions are allocated 50,000 REST API / 10,000 SOAP API calls per day (which resets daily at 12:00AM CST). You can increase your daily quota by contacting Marketo support.
Rate Limit: API access to an instance is limited to 100 calls / 20 seconds.
Concurrency Limit: You can have a maximum of 10 active concurrent API connections with the Marketo instance. Marketo counts the number of concurrent calls as those which are in the processing state and have not yet been returned, so when a call returns, it is no longer counted against the concurrent calls limits.
The size of standard REST calls is limited to a URI length of 8KB, and a body size of 1MB, bulk import/export APIs can have a max payload size of 10 MB.
The batch size for the REST API endpoints' response is 300 records and 200 records for the lead and the asset API endpoints respectively. You can page through/set the offset query parameter for getting the additional records in the response.
Unlike the daily quota limit, which can be increased by purchasing more API calls from Marketo, the rate and the concurrency limits cannot be increased/changed.
Bulk APIs Limits:
- At a given point of time, 2 bulk import/export jobs can be in processing state and 10 jobs can be in the non-completed state (including the 2 in processing state).
- The maximum size of data that could be exported or imported using Bulk API is limited to 10 MB in size.
- Default daily export allocation is limited to 500MB, which is shared between leads and activities (this data export limits can be expanded up to 10 GB against an additional cost).
- When the quota is exceeded, you cannot Create or Enqueue another job until the daily quota resets at midnight Central Time. Until that time, an error “1029, Export daily quota exceeded” is returned.

The following table discusses the error codes for each of the limits enforced by Marketo when the respective limit is reached -

Limit Type	Error Code when limit reached
Daily Quota	607
Rate Limit	606
Concurrency Limit	615
Bulk API Limit – Too many jobs in queue/ Export daily quota exceeded	1029

Besides this, refer this page for all the REST API error codes and description.

All the API limits are enforced for all the API accesses to Marketo by the launchpoint API services. Hence, the number of API users and third-party integration services should always be monitored, and only necessary API integrations should be implemented. Once the allotted limitations are reached, any additional API calls to Marketo will be throttled until the limits get reset at mid-night CT.

Below are some of the recommended best practices to keep in mind while working with the Marketo APIs:

Follow the Principle of Least Privilege by giving API users only those privileges/accesses to the permissions and workspaces that are needed to complete their designated task. By giving permissions to more than needed, you are practically allowing the service using that API user to change/read your Marketo instance's data in more ways than you originally intended.
Use dedicated API users and API services for different integrations as it will facilitate fine-grained control/access over the permissions and would also help in auditing the API usage over the time.
Avoid making concurrent API calls until your use case does not absolutely need it. A single service/integration making concurrent calls could easily eat in the concurrency limit of 10 concurrent calls shared by all the integrations.
To ensure the best performance for your integrations, when performing inserts or updates, group records/updates in as few transactions as possible. Similarly, when retrieving records from a data store for submission, the records should always be aggregated before submission, rather than submitting a request for each individual change, hence saving the precious and limited API calls.
The most efficient way to import/export a large number of records is using Marketo's bulk extract/import APIs which are available for Leads/Persons, Custom Objects, Activities.
Make a practice to cache the Access token instead of making a call to the Identity API to fetch it every single time. This will help to reduce an overhead of making the API calls to GET the access token until the cached token expires. You can cache the access token optimistically and store the age/timestamp with it and re-use the same token until its expiry. Marketo's access token has a life of 60 minutes, after which it needs to be re-generated using the identity endpoint.
It is always advisable to use the REST API over SOAP API for the overlapping functionalities, as REST is any day more secure and efficient.
Certain use-cases benefit from caching the data – e.g., data enrichment, activity types, etc. instead of redundantly making API calls to query the data, it is recommended to query for the data change since last request/filtering data based on the date ranges and appending/updating the cached / stored data.
Monitor your API usages regularly by going to Admin -> Web Services -> API Usage to ensure any services is not overshooting your original expectations/calculations of API calls consumption.
Keep a practice of regularly removing API users, services and integrations which are not in use. For e.g., remove the previously implemented webinar integration when you have changed your webinar provider.
It is not recommended to use the REST/SOAP APIs on the client side - e.g., to retrieve the lead data using email address/tracking cookie as that would put you at risk of DDoS (Distributed Denial of Service) attacks and would make your API creds vulnerable and accessible to the world.
URLs accept only a certain characters, be sure to URI encode the characters not in the standard 128-ASCII character set while not using the auto URI encoding platforms like Postman for making the REST calls.

While this is not an exhaustive list of the Marketo API best practices, but it sure does cover items to help you make the better use of Marketo APIs. Also, if you're just getting started with the APIs, I would recommend going through this Marketo documentation page that'll walk you through creating an API user, a custom launchpoint service, get the access token, and make your first API call.

I hope you found this blog post helpful.

Thank you so much for reading!

- Darshil Shah

Adobe Marketo Engage Champion and Community Advisor