Leads

Last update: December 10, 2024

CREATED FOR:

  • Admin

Leads Endpoint Reference

The Marketo Lead’s API provides a large set of capabilities for simple CRUD applications against lead records, as well as the ability to modify a lead’s membership in static lists and programs, and initiate Smart Campaign processing for leads.

Describe

One of the key capabilities of the Leads API is the Describe method. Use Describe Leads to retrieve a full list of the fields available for interaction via both the REST API, as well as metadata for each:

  • Data type
  • REST API names
  • Length (if applicable)
  • Read-Only
  • Friendly label

Describe is the primary source of truth for whether fields are available for use, and metadata about those fields.

Request

GET /rest/v1/leads/describe.json

Response

{
   "requestId":"37ca#1475b74e276",
   "success":true,
   "result":[
      {
         "id":2,
         "displayName":"Company Name",
         "dataType":"string",
         "length":255,
         "rest":{
            "name":"company",
            "readOnly":false
         },
         "soap":{
            "name":"Company",
            "readOnly":false
         }
      }
}

Normally, responses include a much larger set of fields in the result array, but we’re omitting them for demonstration purposes. Each item in the result array corresponds to a field available on the lead record and will have at minimum an id, a displayName, and a datatype. The rest and soap child objects may or may not be present for a given field, and its presence will indicate whether the field is valid for use in either the REST or SOAP APIs. The readOnly property indicates whether the field is read-only via the corresponding API (REST or SOAP). The length property indicates the max length of the field if present. The dataType property indicates the data type of the field.

Query

There are two primary methods for lead retrieval: the Get Lead by Id, and Get Leads by Filter Type methods. Get Lead by Id takes a single lead id as a path parameter and returns a single lead record.

Optionally you may pass a fields parameter containing a comma-separated list of field names to return. If the fields parameter is not included in this request, the following default fields are returned: email, updatedAt, createdAt, lastName, firstName, and id. When requesting a list of fields, if a particular field is requested, but not returned, the value is implied to be null.

Request

GET /rest/v1/lead/{id}.json

Response

{
   "requestId": "10226#14d3049e51b",
   "success": true,
   "result": [
      {
         "id": 318581,
         "updatedAt":"2015-05-07T11:47:30-08:00"
         "lastName": "Doe",
         "email": "jdoe@marketo.com",
         "createdAt": "2015-05-01T16:47:30-08:00",
         "firstName": "John"
      }
   ]
}

For this method, there will always be a single record in the first position of the result array.

Get Leads by Filter Type will return the same type of records, but may return up to 300 per page. It requires the filterType and filterValues query parameters.

filterType accepts any Custom Field, or most of the commonly used fields. Call the Describe2 endpoint to get a comprehensive list of searchable fields that are permissible for use in filterType. When searching by Custom Field, only the following data types are supported: string, email, integer. You can obtain field detail (description, type, etc.) using the aforementioned Describe method.

filterValues accepts up to 300 values in comma-separated format. The call searches for records where the lead’s field matches one of the included filterValues. If the number of leads matching the lead filter is greater than 1,000 an error is returned: “1003, Too many results match the filter”.

If the total length of your GET request exceeds 8KB, an HTTP error is returned: “414, URI too long” (per RFC 7231). As a workaround, you may change your GET to POST, add the _method=GET parameter, and place a query string in the request body.

Request

GET /rest/v1/leads.json?filterType=id&filterValues=318581,318592

Response

{
    "requestId": "12951#15699db5c97",
    "result": [
        {
            "id": 318581,
            "updatedAt": "2016-05-17T22:11:45Z",
            "lastName": "Lincoln",
            "email": "abe@usa.gov",
            "createdAt": "2015-03-17T00:18:40Z",
            "firstName": "Abraham"
        },
        {
            "id": 318592,
            "updatedAt": "2016-05-17T22:20:51Z",
            "lastName": "Washington",
            "email": "george@usa.gov",
            "createdAt": "2015-04-06T16:29:21Z",
            "firstName": "George"
        }
    ],
    "success": true
}

This call searches for records matching the ids included in filterValues, and returns any matching records.

If no records are found, the response indicates success but the result array will be empty.

Response

{
"requestId": "177a1#1578b643357",
"result": [],
"success": true
}

Both the Get Lead by Id and Get Leads by Filter Type will also accept a fields query parameter, which accepts a comma separated list of API fields. If this is included, then each record in the response will include those listed fields. If it is omitted, then a default set of fields will be returned: id, email, updatedAt, createdAt, firstName, and lastName.

Adobe ECID

When the Adobe Experience Cloud Audience Sharing feature is enabled, a cookie sync process occurs that associates Adobe Experience Cloud ID (ECID) with Marketo leads. The lead retrieval methods mentioned above can be used to retrieve associated ECID values. Do this by specifying ecids in the fields parameter. For example, &fields=email,firstName,lastName,ecids.