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 non-boolean field to filter on, which you can list using the aforementioned Describe method.  When searching by custom field, only the following data types are supported: string, email, integer.

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.

Bulk Import

For large amounts of lead records, leads can be imported asynchronously with the bulk API.  This allows you to import a list of records into Marketo using a flat file with the delimiters (comma, tab, or semi-colon).  The file can contain any number of records, so long as the file totals less than 10MB in size.

Processing Limits

You are allowed to submit more than one bulk import request, with limitations.  Each request is added as a job to a FIFO queue to be processed.  A maximum of 2 jobs are processed at the same time.  A maximum of 10 jobs are allowed in the queue at any given time (including the 2 currently being processed).  If you exceed the 10 job maximum, then a “1016, Too many imports” error is returned.

Import File

The first row of the file must be a header which lists the corresponding REST API fields to map the values of each row into.  A typical file would follow this basic pattern:

email,firstName,lastName
test@example.com,John,Doe
The call itself is made using the multipart/form-data content-type.
This request type can be difficult to implement, so it is highly recommended that you use an existing library implementation.

To make a bulk import request, you need to set your content-type header to “multipart/form-data” and include at least a file parameter with your file content, and a format parameter with the value “csv”, “tsv”, or “ssv” denoting your file format.

A simple way to do this with cURL from the command line looks like this:

curl -i -F format=csv -F file=@leaddata.csv -F access_token=<accesstoken> <REST API Endpoint Base URL>/bulk/v1/leads.json

You can also optionally include the lookupField, listId, and partitionName parameters in your request.  lookupField allows you to select a specific field to deduplicate on, just like Sync Leads, and defaults to email.  listId allows you to select a static list to import the list of leads to; this will cause the leads in the list to become members of this static list, in addition to any creations or updates caused by the import.  partitionName selects a specific partition to import to.  See the Workspaces and Partitions section for more information.

Notice in the response to our call, that there is not a listing of successes or failures like with Sync Leads, but a batchId and a status field for the record in the result array.  This is because this API is asynchronous, and can return a status of Queued, Importing, or Failed.  You will need to retain the batchId in order to get the status of the import job, and to retrieve failures and/or warnings upon completion.   The batchId remains valid for 7 days.

It is best practice to poll the job every 5-30 seconds, depending on required latency and API call limitations, in order to see the status of the import job.  You can do so with the Get Import Lead Status API.

This response shows a completed import, but the status can be one of:

  • Complete
  • Queued
  • Importing
  • Failed

If the job has completed, you’ll have a listing of the number of rows processed, failed, on ones with warnings.  The message parameter may also give the failure message if status is Failed.

To retrieve the records and causes of failed rows, you’ll need to retrieve the failure file:

The API will respond with a file indicating which rows failed, along with a message indicating why the record failed.

To get the warning file you can follow a similar pattern, and it will return a similar response indicating the warnings:

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.