This guide will show you how to make your first call to the Marketo REST API in ten minutes.
We’ll show you how to retrieve a single lead using the Get Lead by Id REST API endpoint. To do this, we will walk you through the authentication process to generate an access token, which you will use to make a HTTP GET request to Get Lead by Id. Then we’ll provide you with the code to make the request that returns lead information formatted as JSON.
How to Generate an Authentication Token
A Custom Service in Marketo allows you to describe and define what data your application will have access to. You need to be logged in as a Marketo administrator to create a Custom Service and associate that service with a single API-Only user.
1. Navigate to the admin area of the Marketo application.
2. Click on the Users & Roles node on the left panel.
3. Create a new role. Reveal the list of role permissions by clicking Access API.
Now scroll down and select only the permissions that you need. In this case, we’ll simply select Read-Only Lead permission.
4. The next step is to create an API-Only user and associating it with the API role that you created in the previous step. You can do so by checking the API-Only user checkbox at the time of user creation.
5. A Custom service is required to uniquely identify your client application. To create a custom application, go to the Admin > LaunchPoint screen and create a new service.
6. Provide the Display Name, choose “Custom” Service type, provide Description, and the user email address created in step 4. We recommend using a descriptive Display Name that represents either the company or purpose of this Custom REST API Service.
7. Click on “View Details” link on the grid to get the Client Id and Client Secret.
Your client application will be able to use the Client Id and Client Secret to generate an access token.
8. Copy and paste your authentication token into a text editor. Your authentication token will look similar to the example below:
cdf01657-110d-4155-99a7-f986b2ff13a0:int
How to Determine the Endpoint URL
In making a request to Marketo API, you will need to specify your Marketo instance in the endpoint URL. All non-bulk API requests to the Marketo REST API will follow the format below:
<REST API Endpoint URL>/rest/
The REST API Endpoint URL can be found within the Marketo Admin > Web Services panel.
Your Marketo endpoint URL structure should look similar to the example below:
https://100-AEK-913.mktorest.com/rest/v1/lead/{id}.json
Note: Bulk API URLs are not prefixed with ‘/rest/’. For Bulk API, you should only use the host, and append the appropriate path like so:
https://100-AEK-913.mktorest.com/bulk/v1/leads/export/create.json
How to use Authentication Token to Call Get Lead by Id API
In the previous sections, we generated an authentication token and found the endpoint URL. We will now make a request to REST API endpoint called Get Lead by Id.
The easiest way to make your request to Marketo REST API is to paste the URL into your web browser address bar. Follow the format below:
https://<REST API Endpoint URL for your Marketo instance>/rest/v1/<API that you are calling>?access_token=<access_token>
Example
https://100-AEK-913.mktorest.com/rest/v1/lead/318581.json?access_token=cdf01657-110d-4155-99a7-f986b2ff13a0:int
If your call is successful, then it will return JSON with the format below:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
{ "requestId": "d82a#14e26755a9c", "result": [ { "id": 318581, "updatedAt": "2015-06-11T23:15:23Z", "lastName": "Doe", "email": "jdoe@marketo.com", "createdAt": "2015-03-17T00:18:40Z", "firstName": "John" } ], "success": true } |
If you are interested in learning more about the Marketo REST APIs, this is a good place to start.