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.

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.

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

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.

By default, the default partition is used.  Optionally, you may specify the partitionName parameter.  During an update operation, if a lead does not exist in specified partition, then an error is returned.  If the API-only user does not have permission to access the specified partition, then an error is returned.

  • The id field can only be included as a parameter when using the updateOnly action, as id is a system managed unique key.
  • If lookupField is email and action is updateOnly, then partitionName is ignored.

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.  The externalSalesPersonId field may be used to link the lead record to a sales person 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.

Fields

The lead object contains standard fields and optionally custom fields.  Standard fields are present in every Marketo Engage subscription whereas custom fields are created by the user as needed.  Each field definition is comprised of a set of attributes that describe the field.  Examples of attributes are display name, API name, and dataType.  These attributes are known collectively as metadata.

The following endpoints allow you to query, create, and update fields on the lead object.  These APIs require that the owning API user have a role with one or both of the Read-Write Schema Standard Field or Read-Write Schema Custom Field permissions.

Query Fields

Querying lead fields is straightforward.  You may query a single lead field by API name or query the set of all lead fields.  Both standard fields and custom fields can be retrieved, depending on the role permissions being used.  Hidden fields are also retrieved.

By Name

The Get Lead Field by Name endpoint retrieves metadata for a single field on the lead object.  The required fieldApiName path parameter specifies the API name of the field.  The response is like the Describe Lead endpoint but contains additional metadata such as the isCustom attribute which denotes whether the field is a custom field.

Browse

The Get Lead Fields endpoint retrieves metadata for all fields on the lead object including .  By default, a maximum of 300 records are returned.  You can use the batchSize query parameter to reduce this number.  If the moreResult attribute is true, this means more results are available.  Continue to call this endpoint until the moreResult attribute returns false, which means there are no results available.  The nextPageToken returned from this API should always be reused for the next iteration of this call.

Create Fields

The Create Lead Fields endpoint creates one or more custom fields on the lead object.  This endpoint provides functionality that is comparable to what is available in the Marketo Engage UI.  You can create a maximum of up to 100 custom fields using this endpoint.

Carefully consider each field that you create in your production instance of Marketo Engage using the API.  Once a field has been created you cannot delete it (you can only hide it).  Proliferation of unused fields is a bad practice that will add clutter to your instance.

The required input parameter is an array of lead field objects.  Each object contains one or more attributes.  Required attributes are the displayName, name, and dataType which correspond to the UI display name of the field, the API name of the field, and the field type respectively.  Optionally you may specify description, isHidden, isHtmlEncodingInEmail, and isSensitive.

There are a few rules associated with name and displayName naming.  The name attribute must be unique, start with a letter, and only contain letters, numbers, or underscore.  The displayName must be unique, and cannot contain special characters.  A common naming convention is to apply camel case to displayName to produce name.  For example, a displayName of “My Custom Field” would produce a name of “myCustomField”.

Update Field

The Update Lead Field endpoint updates a single custom field on the lead object.  For the most part, field update operations performed using the Marketo Engage UI are achievable using the API.  There are a few differences summarized in the table below.

Attribute Standard Field
Custom Field
Updatable by API? Updatable by UI? Updatable by API? Updatable by UI?
dataType no no no yes
description yes yes yes yes
displayName no no yes yes
isCustom no no no no
isHidden no yes yes (if created by API) yes
isHtmlEncodingInEmail yes yes yes yes
isSensitive yes yes yes yes
length no no no no
name no no no no

The required fieldApiName path parameter specifies the API name of the field to update.  The required input parameter is an array that contains a single lead field object.  The field object contains one or more attributes.

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.

Submit Form

Submit Form is an alternative for synchronizing leads to Marketo and is designed to provide functionality that is equivalent to a Marketo Form submission.  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 Submit Form endpoint supports the following functionality:

  • Upserts a lead record using email field as primary key
  • Creates a “Fill out Form” activity which is associated back to a program and/or campaign
  • Allows lead association based on cookie value
  • Performs form field validation

Submitting a form follows the standard lead database pattern.  A single object record is passed in the required input member of the JSON body of a POST request.  The required formId member contains the target Marketo form ID.

The optional programId can be used to specify the program to add the lead to, and/or specify the program to add program member custom fields to.  If programId is provided, the lead is added to the program and any program member fields present in form are also added.  Note that the specified program must be in the same workspace as the form. If form does not contain program member custom fields and programId is not provided, then lead is not added to a program.  If form resides in a program and programId is not provided, that program is used when one or more program member custom fields are present in form.

Within the input record, the leadFormFields object is required.  This object contains one or more name/value pairs that correspond to the form fields to populate.  All fields specified must be defined within the specified form.  The name is the REST API name for the field.  Note that the email field is required.

The visitorData member object is optional and contains name/value pairs that correspond to page-visit data including pageURL, queryString, leadClientIpAddress, and userAgentString.  Can be used to populate additional activity fields for filtering and triggering purposes.

The cookie member string is optional and allows you to associate a Munchkin cookie with a person record in Marketo.  When a new lead is created, any prior anonymous activities will be associated with that lead, unless the cookie value had previously been associated to another known record.  If the cookie value was previously associated, then new activities will be tracked against the record, but old activities will not be migrated away from the existing known record.  To create a new lead with no activity history, simply omit the cookie member.

New leads will be created in the primary partition for the workspace in which the form resides.

And here we can see the corresponding “Fill Out Form” activity details from within the Marketo Engage UI:

 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.

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.  The leads specified in either leadId or leadIds parameter are the losing leads.

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.

Membership

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.

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.

Programs

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.

Delete

Removing leads is straightforward using Delete Leads endpoint.  Specify lead ids to delete using the id attributes in body.  The maximum is 300 leads per request.  Use Content-Type: application/json header.

 

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

Timeouts

  • Leads Endpoints have a 30s timeout unless noted below
    • Sync Leads: 90s
    • Associate Lead: 60s
    • Merge Leads: 180s
    • Update Lead Partition: 60s 
    • Push Lead to Marketo: 90s 
    • Get Leads by Filter Type: 60s 
    • Get Leads by List ID: 60s