REST API

Marketo exposes a REST API which allows for remote execution of many of the system’s capabilities.  From creating programs to bulk lead import, there are a large number of options which allow fine-grained control of a Marketo instance.

These APIs generally fall into two broad categories: Lead Database, and Asset.  Lead Database APIs allow for retrieval of, and interaction with Marketo person records and associated object types such as Opportunities and Companies.  Asset APIs allow interaction with marketing collateral and workflow-related records.

  • Daily Quota: Most subscriptions are allocated 50,000 API calls per day (which resets daily at 12:00AM CST).  You can increase your daily quota through your account manager.
  • Rate Limit: API access per instance limited to 100 calls per 20 seconds.
  • Concurrency Limit:  Maximum of 10 concurrent API calls.

 

The size of standard calls is limited to a URI length of 8KB, and a body size of 1MB, though the body can be 10MB for our bulk APIs.  If there is an error in with your call, the API will typically still return a status code of 200 OK, but the JSON response will contain a “success” member with a value of false, and an array of errors in the “errors” member.  More on errors here.

Getting Started

The following steps require admin privileges in your Marketo instance.

For your first call to Marketo, you’ll simply retrieve a lead record.  To begin working with Marketo, you need to obtain API credentials so that you can make authenticated calls to your instance.  First you’ll need login to your instance and go to the Admin menu, then to Users and Roles.

doc-rest-api-admin-users-and-roles

Click on the Roles tab, and then New Role and assign at least the “Read-Only Lead” permission to the role in the Access API group.  Be sure to give it a descriptive name and click on Create.

doc-rest-api-new-role

Now back to the Users tab and click on Invite New User.  Give your user a descriptive name that indicates that it is an API user, as well as an Email Address and click on Next.

doc-rest-api-new-user-info

Then, check the API Only option and award your user the API role that you just created and click on Next.

doc-rest-api-new-user-permissions

To complete the user creation process, click on Send.

doc-rest-api-new-user-message

Next, go to the Admin menu, then to LaunchPoint.

doc-rest-api-admin-launchpoint

Click on the New menu and select New Service.  Give your service a descriptive name and select Custom from the Service dropdown menu.  Give it a description, then select your new user from the API Only User dropdown menu and click on Create.

doc-rest-api-admin-launchpoint-new-service

Click on View Details for your new service to access the Client ID and Client Secret.  For now you can click the Get Token button to generate an access token which will be valid for one hour.  Save the token in a note for now.

doc-rest-api-get-token

Next, go to the Admin menu, then to Web Services.

doc-rest-api-admin-web-services

Find the Endpoint in the REST API box and save in a note for now.

doc-rest-api-admin-web-services-rest-endpoint

Open a new browser tab and enter the following, using the appropriate information to call Get Leads by Filter Type:

If you don’t have a lead record with your email address in your database, just substitute it for one that you know is there.  Hit enter in your URL bar, and you should get back a JSON response resembling this:

Congratulations, you’ve successfully sent your first REST API call to Marketo!

API Usage

Each of your API users is reported individually in the API usage report, so splitting up your web services by user allows you to easily account for the usage of each of your integrations. If the number of API calls to your instance are exceeding the limit and causing subsequent calls to fail, using this practice will allow you to account for the volume from each of your services and let you evaluate how to resolve the issue. See your usage by going to Admin -> Web Services and clicking on the number of calls in the past 7 days. You can also get the same information from the Usage APIs

API
Per Users