The Marketo Object Model (including a SOAP’s Perspective)
The primary object in the Marketo Data Object Model is the Marketo Lead Object. This Lead Object is comprised of standard data fields that are commonly used for lead capturing & nurturing and overall lead management.
Marketo also allows an Admin the ability through the Admin->Field Management menu to create custom fields off of the lead object to create & expose fields that may be specific to your business use case(s).
Marketo Leads can be Created, Read & Updated (CRU) via the Marketo SOAP API via the syncLead, syncMultipleLeads and getLead SOAP API methods. The importToList API call can also be used to add Leads to Marketo. The importToList call is the API version of the List Import functionality exposed in Marketo. Note that the SOAP API does NOT expose the ability to delete a lead.*
* A common lead deletion workaround is to set a specific custom field value which triggers a pre-configured smart campaign in Marketo to delete that lead. Another method is to add the lead to a campaign (see RequestCampaign API) that is designed to delete the lead.
It is important to note that not all Fields in Marketo are exposed via the API, a common way to get a list of your accounts’ fields that are exposed in the API is under Admin->Field Management and download the field list with API names. If there is a field that you wish to expose via the API that is not available (i.e. Inferred IP/Data), you will need to create a smart campaign to copy the value into a new custom field you created since all custom fields by default are available via the SOAP API.
Note that there is another Marketo SOAP API call, getMultipleLeads, that is typically used as a basis for API based integrations between Marketo and another platform (i.e. CRM, Data Warehouse, etc.). This API call will:
- Bring back Marketo leads (with their fields that contain values not null) that have changed since a specific date. Therefore, if you store the Last Run Date in your application, you can use it as a parameter on this call to bring back Leads that have had any field value changes since the last time you made the call.
- Bring back Marketo leads (with fields that contain values not null) that belong to a specific list (new in version 2.0)
- Bring back Marketo leads (with fields that contain values not null) that are part of the passed in lead key list (new in version 2.0)
Throughout the Marketo lead’s lifecycle, Marketo will be recording activities around actions that the lead takes (i.e. Filled Out a Form, Visited Web Page, Clicked Link, etc.) and actions that are taken upon the lead (i.e. data value changed, moved to next progression step, added to a smart campaign etc.).
There are two ways to view the activities that have been recorded for that lead.
1) You can view the activities for a specific Lead by going into Marketo Lead Management (UI) and click on the Activity tab for that Lead.
2) You can use the SOAP API*
* The list of all activity types is accessible via the WSDL. Click here for the v2.0 version of the WSDL (version at the time of this posting)
The SOAP API exposes two methods to get Activities. The getLeadActivity will return activities for a single lead (either all activities or specific activities you are interested in). The second SOAP API call is getLeadChanges which will return all activities for all leads. Of course that can grow to become an INSANELY LARGE amount of activities so the API allows you to filter on activities created since a certain date range and/or specific activity types to include/exclude.
Click here for a post that shows some Activity XML using real world activity types such as VisitWebPage, FillOutForm, ClickEmail, ClickLink and Interesting Moments.
Opportunity & OpportunityPersonRole Object (MObjects)
As Marketo Leads flow through the funnel they can be touched by many programs/campaigns each of which having their own associated costs. A typical scenario is that a lead starts in Marketo (via a Marketo Form Fill Out) and is nurtured. At some point, that Marketo Lead reaches a scoring threshold and is triggered to be sent to the CRM… the CRM will
- Create a Contact
- Associate the Contact to an existing Account or a new Account
- An Opportunity is created to be followed upon.
The Sales Rep works with that Opportunity and at some point that Opportunity is closed out (i.e. Closed Won, Closed Lost, etc.).
A native Marketo integration (i.e. SFDC, MSCRM Dynamics) will out of the box bring opportunity information into Marketo from the CRM but for non-native integrations, Marketo has exposed the Opportunity & OpportunityPersonRole Objects via the SOAP API (see the get-sync-deleteMObject API calls), to fully support the loading of opportunity data into Marketo for use with Program Analysis as well as for the Revenue Cycle Analytics (RCA) add-on product.
Click here for more information on how to use the Marketo SOAP API to load Opportunity Information into Marketo.
Their exists scenarios where a “one to many” relationship is needed to be captured on a per lead basis. Common use cases for this are in trial version or freemium model where a lead may have signed up or registered one or more times for one or more products using an e-commerce platform or custom web application and this data is stored locally in a data warehouse.
Marketo can be used to create nurture programs & campaigns around each of those registrations but since each of those registrations may have different criteria, lead registration status, etc. it would require that the lead be placed in a different nurture track (program/campaign) based on its segmentation.
This is where Custom Objects come in handy. A native Marketo integration (certainly SFDC but not sure about MSCRM Dynamics) has built in sync capabilities to allow the ability to sync a Custom Object that was created in the CRM over to Marketo. Adding the object to the sync can be configured in the Admin->SFDC Menu.
For non-native integrations, contact firstname.lastname@example.org to get a Custom Object provisioned to your account as part of a Services Engagement. The cost is $2K per custom object at the time of this posting as it requires a schema definition exercise with a Professional Services specialist to help define the custom object, field names/types, Unique Key & LeadIdentification Fields and to get it provisioned to the account.
NOTE: Custom Objects that come through via the native sync are NOT accessible via the SOAP API. You must use the CRM Interface or API to manipulate (i.e. CRUD) the Custom Object data. Custom Objects that were created via a Services Engagement are accessible via the SOAP API using the syncCustomObjects and deleteCustomObjects API calls.
Once the Custom Object exists in Marketo (either via the native sync or via a Services Engagement described above), the Custom Object can now be used as part of a trigger or filter.
For example, you can create a Smart Campaign that triggers off a value that has changed on a specific field on a Custom object. Those who are triggered will get added to the Smart Campaign.
Or you can create a Smart List that is segmented as Having a Custom Object Record and a specific value on a field. The Smart List will return all Leads who fit that criteria.
IMPORTANT NOTE: As of this posting, it is
- Not possible to view the data in records that exists in a Custom Objects belonging to a lead(s).
- Not possible to directly use any data in records as the source for a dynamic value in a campaign, email, etc.
So is there a Marketo Company Object or not? Looking at a lead in Marketo and selecting a specific Lead, you will that the Lead’s data is categorized into multiple tabs (i.e. Lead Tab, Company Tab, etc.)
Looking at this screen, you may be inclined to believe that there exists one Marketo Object for each of the tabs and therefore there does exist a Marketo Lead Object that corresponds with the Lead Tab and a Marketo Company Object that corresponds with the Company Tab.
“OK, so there does exist a Marketo Company Object, right?”
If you review the SOAP API documentation around the getLead call and the syncLead call, you would be inclined to think that the Marketo Object Model only contains a Lead Object and does NOT have a separate Company Object. Two reasons why you would be led to believe this is that:
1) When you make a getLead call it not only returns fields such as First Name & Last Name BUT IT ALSO returns fields like Company Name, Number of Employees, Website, etc. (fields on the Company Tab in Marketo)
2) There is a syncLead (syncMultipleLead) but no such call as a syncCompany or syncMultipleCompanies call. The syncLead & syncMultipleLeads calls are the only calls to use when setting values to fields like First Name, Last Name AND ALSO Company fields like Company Name, Number of Employees, Website, etc.
“So wait, there is not a Marketo Company Object?”
If all of the fields on the Company tab are accessible via the API using the getLead, syncLead or syncMultipleLeads calls and there is neither a getCompany nor a syncCompany API call then “is there really a Marketo Company Object in the Marketo Object Model?”
The answer is yes, there does in fact exist a Marketo Company Object and it is used on Marketo | CRM native integrations (SFDC & MS CRM Dynamics) only as part of the CRM Account Object sync process. This is good as it means that if a value changes on an account field in CRM, it will get reflected on all Leads in Marketo that are synced to that Contact belonging to that CRM Account.
For example, let’s use the scenario where there exists
- Two Marketo Leads
- They are synced to two CRM Contacts
- Those two CRM Contacts belong to the same CRM Account, for example, ACME Co.
- If a sales rep changes the Company Name from ACME Co. to ACME Inc.
- The native integration sync WILL update the Company Name for BOTH of the Marketo leads to reflect the Company Name change of ACME Inc.
It still stands though that for non-native integrations where the SOAP API is being used, the fact that there is no Company Object exposed via the API means that for every CRM Contact that belongs to that CRM Account, you will need to make a separate syncLead (syncMultipleLead) call to update the Company Name field for each of the Marketo leads to reflect that Company Name change.
Further, if you are using ROI reporting in Marketo and/or Revenue Cycle Analytics (RCA), you will need to be sure that the Opportunities are linking to the correct Company/Account so that the ROI data is being properly associated with the correct Marketo Company Object (which again is not directly exposed via the SOAP API). Click here to learn how to make sure that Marketo Leads that belong to a Company/Account for which an Opportunity belongs get proper attribution for Opportunity / Revenue Analysis (RCA).
Although there exists a Marketo Campaign Object, it is native to Marketo and is not exposed via the SOAP API. In other words, it is not an Object that is exposed via the API with Create, Read, Update or Delete (CRUD) functions. The ways to interact with Marketo Campaigns are as follows:
- The getCampaignsForSource API call returns all Campaigns that were created in Marketo that were marked to be triggered Campaign is Requested | Source is Web Service API. You can think of this API call as a kind of “return a list of all Marketo campaigns available to the API.”
- The requestCampaign API call allows you to add a specific lead or list of leads to a pre-configured Marketo campaign. This allows you to add lead(s) to a campaign that will for example, send a pre-configured email (i.e. registration, than you, etc.) or add the lead(s) to a nurture campaign. Again, the campaign must be already configured/activated in Marketo and set to be Campaign is Requested | Source is Web Service API. This call will immediately add the lead(s) to that campaign. More information on this call can be found in the SOAP API document.
- The scheduleCampaign API call allows you to schedule a batch Smart campaign in Marketo. More information on this call can be found in the SOAP API document.
- Note that another method to trigger a campaign for a lead(s) is to set up a Marketo campaign that is triggered by a field value changing for that lead (data value changed trigger). Then at any point, making a syncLead (syncMultipleLead) call and changing this value will add the lead to the campaign. See Appendix C in Marketo SOAP API doc for some more info on this method.
- Another method is to use the importToList method. Adding a lead(s) to a list can be set up as the trigger for a Marketo campaign. See Appendix C in Marketo SOAP API doc for some more info on this method.