How to Specify Lead Partitions Using the REST API

September 4, 2015 | by

Lead Partitioning

Marketo Lead Partitions provide a convenient way to isolate leads.  Partitions can allow different marketing groups within your organization to share a single Marketo instance.  For more information, see Understanding Workspaces and Lead Partitions.

Suppose that you are using lead partitions and creating leads programmatically using the Marketo REST API.  How do you ensure the leads that you create will end up in the correct partition?  This post will show you how!

For the sake of this example, we’ll use Workspaces and Partitions to isolate our leads based on geography.  First we’ll define a workspace called “Country”.  Next, we’ll create two partitions within that workspace called “Mexico” and “Canada”.

edit_workspace

Create Lead in Partition

Suppose now that we want to create two leads in the “Mexico” partition.  To create leads, we call the Create/Update Leads API.  To specify the partition, we must include the “partitionName” attribute in the request body.

How do we know what to use for the partitionName value?  We can retrieve a list of valid partition name values for our instance by calling the Get Lead Partitions API as follows:

In this case, the correct value is “Mexico”, so we then pass that to Create/Update Leads as follows:

Here are our newly created leads in Marketo.
lead_create

Update Lead in Partition

To update existing leads in a partition, we simply call Create/Update Leads and specify partitionName the same as we did before. For this update, we’ll assign first name, last name, and title to the leads that we created above.

Here are our newly updated leads in Marketo.
lead_update

Identify Partition for a Lead

How do we know which partition that a lead is in?  For this we use the Get Lead by Id API and specify “leadPartitionId” in the “fields” query parameter.  In this case we will retrieve the information for lead id 318816 that we created above.

Note that we get back leadPartitionId rather than the partitionName.  To get the partitionName we need to revisit the output from Get Lead Partitions API from above.

In this case a leadPartitionId value of 2 maps to partitionName of “Mexico”.

That’s all for now.  Happy partitioning!