Leads

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

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:

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 of the fields listed below, and also all custom fields.

  • id
  • cookies
  • email
  • twitterId
  • facebookId
  • linkedInId
  • sfdcAccountId
  • sfdcContactId
  • sfdcLeadId
  • sfdcLeadOwnerId
  • sfdcOpptyId

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”.

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.

Supported filter types include, but are not limited to:

  • id
  • cookies
  • email
  • twitterId
  • facebookId
  • linkedInId
  • sfdcAccountId
  • sfdcContactId
  • sfdcLeadId
  • sfdcLeadOwnerId
  • sfdcOpptyId
  • custom field

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.

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 lookupField parameters are required, and the source and reason parameters are optional.  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 and filters.

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

 Merge

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.

A note regarding Marketo Custom Objects.  If the losing lead record is the parent of one or more Custom Objects, then merging leads does not combine those Custom Objects with the winning lead record.  Therefore, all Custom Objects on the losing lead record must be re-parented to the winning lead record before attempting to merge leads.

 

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.

List and Program Membership

Lead records can also be retrieved based on membership in a static list or a program.  Using the id of a static list, you retrieve all lead records which are members of that static list. The id of the list is a path parameter in the call.

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

Program membership can be retrieved in a similar fashion as lists.  The same optional request parameters are available.

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, additionally showing reachedSuccessDate if reachedSuccess is true.  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.

Relationships

    • 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.