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.


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 and SOAP API, as well as metadata for each:

  • Data type
  • REST and SOAP 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.

Normally, responses will 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.


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 will be 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.

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 will accept 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 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 will accept up to 300 values in comma-separated format. The call will search 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 _method=GET parameter, and place query string in the request body.

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

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

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.

Create and Update

In addition to retrieving lead data, you can create, update and delete lead record via the API.  Creating and updating leads share the same endpoint with the operation type being defined in the request, and up to 300 records can be created or updated at the same time.

In this request, you’ll see two important fields, action and lookupField.  action specifies the operation type of the request, and can be createOrUpdate, createOnly, updateOnly, or createDuplicate.  If it is omitted, the action defaults to createOrUpdate.  The lookupField parameter specifies the key to use in the operation.  If lookupField is omitted, the default key is email.

The id field can only be included as a parameter when using the updateOnly action, as id is a system managed unique key.

The request must also have an input parameter, which is an array of lead records.  Each lead record is a JSON object with any number of lead fields.  The keys included in a record should be unique for that record, and all JSON strings should be UTF-8 encoded.  The externalCompanyId field may be used to link the lead record to a company record.

Note: When performing lead upsert requests concurrently or in quick succession, duplicate records may result when making multiple requests with the same key value if a subsequent call with the same value is made before the first returns.  This can be avoided either by using the createOnly, or updateOnly as appropriate, or by queuing calls and waiting for your call to return before making subsequent upsert calls with the same key.

Push Lead to Marketo

Push Lead is an alternative for synching leads to Marketo, primarily designed to allow a greater degree of triggerability than the standard Sync Leads (similar in usage to a Marketo form).  In addition to synchronization of lead fields, this endpoint allows for lead association based on cookie values which are passed to the endpoint.  This is done by passing the mkt_tok value generated by clicking through a Marketo email, or by passing a program name in the call.  This endpoint also creates a single triggerable activity which is associated back to a program and/or campaign in Marketo.  This allows triggering on lead capture events which are attributed to a specific campaign or program to kick off associated workflows from within Marketo.

The Push Lead interface is very similar to Sync Leads.  All of the same primary keys are valid, and the same API names are used for fields (there is no action parameter because this is always an upsert operation).  The programName and input parameters are required, and the lookupFieldsource, and reason parameters are optional.  The input parameter is an array of lead objects.  The resulting activity will be attributed to the corresponding named program.  The source and reason parameters are arbitrary string fields which can be added to the request to embed those values in the resulting activities. These may be used as constraints in the corresponding triggers (Lead is Pushed to Marketo) and filters (Lead Was Pushed to Marketo).

Note regarding anonymous activities.  If you want to associate prior anonymous activities with the newly created lead, then do not specify cookies attribute in lead object, and call Associate Lead following Push Lead.  If you want to create a new lead with no activity history, then simply specify cookies attribute in lead object.

To pass the mkt_tok parameter, assign the value to the mktToken member within a lead record in the input parameter as follows.


Sometimes it is necessary to merge duplicate records and Marketo facilitates this through the Merge Leads API.  Merging leads will combine their activity logs, program, campaign, and list memberships and CRM informations, as well as merge all of their field values into a single record.  Merge Leads takes a lead id as a path parameter, and either a single leadId as a query parameter, or a list of comma-separated ids in the leadIds parameter.

The lead specified in the path parameter is the winning lead, so if there are any fields in conflict between the records being merged, the value from the winner will be taken, except if the field in the winning record is empty and corresponding field in losing record is not.

If you have an SFDC-sync enabled subscription, then you can also use the mergeInCRM parameter in your request.  If set to true, the corresponding merge in your CRM will also be performed.  If both leads are in SFDC and one is a CRM lead and the other is a CRM contact, then the winner is the CRM contact (regardless which lead is specified as winner).  If one of the leads is in SFDC and the other is Marketo only, then the winner is the SFDC lead (regardless of which lead is specified as winner).

Associate Web Activity

Through Lead Tracking (Munchkin), Marketo records web activity for visitors to your Web Site and Marketo Landing Pages.  These activities, Visits and Clicks, are recorded with a key which corresponds to a “_mkto_trk” cookie set in the lead’s browser, and Marketo uses this to keep track of the same person’s activities.  Normally, association to lead records occurs when a lead clicks through from a Marketo email or fills out a Marketo form, but sometimes an association can be triggered by a different type of event, and you can use the Associate Lead endpoint to do so.  The endpoint takes the known lead record’s id as a path parameter and the “_mkto_trk” cookie value in the cookie query parameter.

If a cookie is already associated to a known lead record, using this API on a different lead record will cause new web activity to be recorded against that record, but will not move any existing web activity to the new record.


Lead records can also be retrieved based on membership in a static list, or a program.  Additionally, you can retrieve all static lists, programs, or smart campaigns that a lead is a member of.

Static Lists

The Get Leads by List Id endpoint takes a single listId path parameter and returns all lead records that are members of a static list.

The endpoint may return fewer leads than requested in batchSize.  When more records are available for retrieval, the response will return a value for nextPageToken.  To retrieve the next set of records, subsequent calls must pass the nextPageToken value from the previous call.  When all the leads in a list are returned, your next call will result in an empty result array.  This is the terminating condition when iterating through the list.

The response structure and optional parameters are identical to those of Get Leads by Filter Type, though filterType and filterValues cannot be used in conjunction with this API.

To access the list id through the Marketo UI, navigate to the list. The list id will be in the URL of the static list, https://app-****.marketo.com/#ST1001A1. In this example, 1001 is the id for the list.

The Get Lists by Lead Id endpoint takes a lead record id path parameter and returns all static list records that the lead is a member of.


Program membership can be retrieved in a similar fashion as lists.  The same optional request parameters are available when calling the Get Leads by Program Id endpoint and pass programId path parameter.

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 will be returned: email, updatedAt, createdAt, lastName, firstName, membership, and id.  When requesting a list of fields, if a particular field is requested, but not returned, the value is implied to be null.

The response structure is very similar, as each item in the result array is a lead, except that each record also has a child object called “membership.”  This membership object includes data about the lead’s relationship to the program indicated in the call, always showing its progressionStatus, acquiredBy, reachedSuccess, and membershipDate.  If the parent program is also an engagement program then membership will also have members stream, nurtureCadence, and isExhausted to indicate its position and activity in the engagement program.

The Get Programs by Lead Id endpoint takes a lead record id path parameter and returns all program records that the lead is a member of.  The optional filterType and filterValues  parameters allow you to filter on program Id.

Smart Campaigns

The Get Smart Campaigns by Lead Id endpoint takes a lead record id path parameter and returns all smart campaign records that the lead is a member of.


Removing leads is straightforward.  Use the HTTP POST method and pass _method=DELETE parameter.  Specify lead ids to delete using the id attributes in body.  The maximum is 300 leads per request.  Use Content-Type: application/json header.



    • Opportunities through OpportunityRoles: leadId and externalOpportunityId field
    • Companies through externalCompanyId field on lead record
    • SalesPersons through externalSalesPersonId field on lead record
    • Programs through program membership
    • Lists through list membership
    • Activities through leadId field on the activity
    • Segmentations through individual segment fields on lead record
    • Partitions through leadPartitionId on lead record