Screen Shot 2015-06-19 at 3.56.29 PM.png

Custom Objects 2.0 in Marketo - Part 1

Marketo Employee
Marketo Employee

"Marketo only" custom objects have been available for a while within Marketo, but up until recently you needed involvement from Support or Consulting to create them. Well, all that is changing in a recent enhancement to Marketo. If you need to leverage Custom Objects, you can request access via support, and this new end user facing UI is all yours. Amazing, Right?

Screen Shot 2015-06-19 at 3.56.29 PM.png

Once enabled, you'll see the Custom Objects under Admin --> Custom Objects

Lets talk a bit about why you might need or want to use custom objects. Custom objects are used to extend the Marketo data model and specify data that exists in a one to many relationship with a Lead or Company. Example of this might be "Products" or "Contracts" or "Investment Portfolios".. the possibilities are endless.

These objects, one created and published are populated using the SOAP or REST API and can be used in Smart Campaigns or Smart lists, and are viewable in the Lead Details screen under "Custom Objects"

The available Triggers and Filters for an object called "Literature" would be


     Added to Literature - A Literature Object was added to a lead


     Was Added to Literature

     Has Literature

     Was Not Added to Literature

and as you can see.. the attributes of the Custom Object become constraints on the Filters and Trigger.

Screen Shot 2015-06-19 at 4.30.45 PM.png

Another cool way you can use custom objects is within Email Scripts! You can, for example, create a dynamic script token for an email that when the email is sent, shows all the values for a custom object in the system. You might use this to list out a set of stocks owned by a person, or a list of historical purchases. That will be discussed further in the Email Script sequel to this post.

Creating Custom Objects

Now that you know what they are and how to use them... how do you create them? Excellent question, and it's not hard. Firstly you need to design your object.

Custom objects, when created, are given 3 fields by default: Created At, Updated At, and Marketo GUID. The first two are obvious, but the Marketo GUID can serve as a unique identifier for the custom object.

Screen Shot 2015-06-19 at 4.43.29 PM.png

In addition to these fields you MUST create the following fields

  • a "Link" field - This field is the field that connects an object to the appropriate Marketo Lead or Company. you can choose Email Address, Marketo ID, or any custom field (Perhaps your company uses a unique "integration ID" for leads?). Please note. Be careful when creating the link field. This field, when you add data, MUST be a field that exists on the Lead or Company, and obviously must have a value on the Lead or Company that matches what you're upserting. Also, Ensure that the NAME and API NAME on the custom object match the API NAME on the Lead or Company. Trust me on this.

Screen Shot 2015-06-19 at 4.44.56 PM.png

  • a "Dedupe" field - This is another unique identifier that you can use to UPDATE existing custom objects once they're in Marketo. For example....if you're building a custom object called "Automobile" the Dedupe Field might be "VIN Number", which uniquely identifies the Automobile. When you go to update these objects, this is the field you use to identify the custom object, along with its associated Lead (Change the automobile with Vin=12345678 to now have a Color of "Green"). You can have one or more of these, as described in the special note below.

Screen Shot 2015-06-19 at 4.53.22 PM.png

Optionally, you can add other fields (Color, Make, Model, would be good candidates for an Automobile, so I'll add those, as shown.Screen Shot 2015-06-19 at 4.53.49 PM.pngHere's an important note. There are times youll have dedupe fields that are TRULY unique across your Marketo instance, things like Social Security Number or VIN Number.. you're sure no two people will own the same Car with the same VIN Number at the same time.Sometimes, however, you have dedupe fields that are NOT unique. Think about the example of a Product ID. A product like a smart phone might be assigned a product ID of ABC123. In that case, John and Mary might both own this product. In that case, youll have ProductID as a dedupe field, Email address as a link field AND a dedupe field! It will then the the COMBINATION of email and ProductID that constitute a unique custom object of type Product.Looking good! You might be wondering.. is the object live yet? No, not yet.. so lets talk state. The state of a Custom Object can be discussed for two aspects, the state of the object itself, and the state of a field on the object.Possible states are:

  • Object: Draft, Published, Published with Draft
  • Attribute: New, Deleted

Right now, all of our fields are "new" and the object itself is "Draft". To publish it so it's available for use, just click the publish button and see that these statuses change. Up until you publish the object you can change things about the object like the key fields etc.. but once its published, those key fields are locked down.. including the Link and Dedupe fields.

Screen Shot 2015-06-19 at 4.57.00 PM.png

Screen Shot 2015-06-19 at 4.58.15 PM.png

Once you're object is published, you can use it, and load it up with data using the REST or SOAP APIs (see  next week's blog on that)... or even BULK LOAD data. You read that right. Hop over to the Lead Database and you'll see New --> Import Custom Object Data. This option works a lot like importing leads. You can import a CSV and map the fields into your object. Obviously you'll have to include the link field, the dedupe fields and the data fields. You're limited to ~100mb per file.. and you can expect very high speed imports (up to 1,000,000 per hour)

Changing an Existing Object

Previously, this was awful and involved deleting the object data, dropping the object and recreating the object. No more! You're free to remove columns, add columns, and then republish the object! Click "new" to add a new field, and right click a deletable field and click "delete" to see those other two attribute states.

Screen Shot 2015-06-19 at 5.02.21 PM.png

As before.. NOTHING changes from an API or application perspective until you push the publish button.. then the changes are live.

Next up.. Custom Objects in Marketo - Part 2 - REST API !!!

Not applicable


Great to see all the details about custom objects.

You mentioned it is in Beta right now, can you please guide us on how can we get on the beta for custom objects.

Not applicable

I see mention of being able to create a dynamic script token for an email that when the email is sent, shows all the values for a custom object in the system. Where would that token show up based on the example above (i.e. would it be {{lead.Automobile}} or {{lead.Has Automobile}} or something else?).

My custom object is set to show in "Lead Detail," the example above has show in "Lead Grid." I did not see the Lead Grid option when I built my custom object. Has there been changes to these options? John MattosAndrew Welch

Level 1

The feature is now launched and officially supported!

Level 1

The script token in question would be defined at, for example, the program level. Check out Email Scripting » Marketo Developers

It would look something like this in your email {{my.Custom Object Data}} the examples you gave above are lead attributes.. thats nohow you extract information from the custom object... remember, there might be many of these for a given lead, so that format wouldn't work.

Not applicable

So I was able to pull in the custom object field values into an email using the "Email Script" token. Thanks for your response above John Mattos.

Now I am curious if there is any way to be able to apply that token in a "change data value" flow step to update a field in our system with the custom object field values? Below is the flow step I attempted. The field was populated with the actual token "{{my.Custom Object Script}}" when I ran the smart campaign, instead of the custom object values (I am trying to consolidate questions and answers from webinars into a single notes field that I have populated in a custom object):


Marketo Employee

Unfortunately you cant reference tokens like that... mostly because remember the custom objects are one to many with leads.. so there's no way to know which one you were referring to. What are you trying to accomplish.. I'm not 100% clear on that.

Not applicable

My goal here is to take the survey question and answers we receive from our webinars with ReadyTalk and enter the Q/A values into one regular text field (currently this is a long manual process). When our Sales team reaches out to the lead they can see what types of Q/As they had. I was hoping custom objects could help us automate this manual task.

Currently I have built an integration with ReadyTalk where the Q/As populate after each webinar through a REST API:


From here I would like to take those custom object field values and consolidate them into one text field in MLM (which I could not figure out).

Currently I was considering creating an alert email that could be sent displaying all the Q/As from the webinar:


Any suggestions?

Not applicable

Can you also add this update to the docs page for Custom Objects? I tend to look there first.


Not applicable

Hi John Mattos (W), thanks for this, very helpful. Once a Marketo Custom Object is setup and live, can you write to it via a Marketo form? E.g. You are a real estate company and you want to write each landlord's property they have listed to the custom object. Each landlord could have 5 properties, so Custom Objects would work for this case I think. But my main question is can they be populated via a form?

We also have Salesforce, so if we setup a custom object there, could a Marketo Form write to this? Thanks v. much

Marketo Employee

Renault NZ​ unfortunately no. Custom objects can only be populated via REST API, SOAP API, and import. Same for SFDC objects really.. those are READ ONLY within marketo.. so you'd have to use some other method like the SFDC REST API to populate those (non marketo forms).. then you'd make a REST call into marketo to update lead data and presumably the SFDC custom objects would flow into marketo separately.