Migrating to REST API

Last update: December 19, 2024

CREATED FOR:

  • Admin

The Marketo Engage SOAP API will be retired after October 31, 2025. All existing integrations using the SOAP API should be retired or migrated to the Marketo Engage REST API by this date in order to avoid interruptions in service.

Migration

The SOAP API supports a limited range of use cases compared to the REST API. When determining which endpoints to map your use cases, you should follow Marketo Integration Best Practices

Reference Architectures are available for CRM Synchronization and Data Warehouse Export use cases.

Authentication

Authentication Documentation

The Marketo REST API uses OAuth 2.0 based authentication with the Client Credentials grant type. Access tokens are valid for one hour after creation.

Leads

Lead API Documentation

The SOAP API supports lead data synchronization, Munchkin cookie association, and lead merging. If your application calls the SOAP syncLead method and sets the marketoCookie parameter, you can migrate by either:

  1. Using the Sync Leads REST method, followed by Associated Lead
  2. You can call Submit Form, though this requires configuration of some Marketing Assets and some interaction with the Forms API

Applications which use the foreignSysPersonId key type, should migrate to using a custom lead field to represent this external identifier, and use either Sync Leads or Bulk Lead Import REST Methods.

SOAP MethodREST Method(s)
getLeadGet Lead by ID, Get Leads by Filter Type
getMultipleLeadsGet Lead by ID, Get Leads by Filter Type, Get Leads by Program ID, Get Leads by List ID, Bulk Lead Export
mergeLeadsMerge Leads
syncLeadSync Leads Submit Form Associate Lead
syncMultipleLeadsSync Leads Bulk Import

M Objects

M Objects was a catch-all concept to support export of Opportunity Attribution data for external analysis, and worked with three object types: Opportunities, Opportunity Roles, and Programs.

REST Documentation:

SOAP MethodREST Method(s)
deleteMObjectsDelete Opportunities, Delete Opportunity Roles
describeMObjectsDescribe Opportunity, Describe Opportunity Role
getMObjectsGet Opportunities, Get Opportunity Roles
listMObjectsN/A
syncMObjectsSync Opportunities, Sync Opportunity Roles
getChannelsGet Channels
getTagsGet Tag Types, Get Tag by Name

Static Lists

Static List Use cases in the SOAP API are limited to ingestion of membership and lead data, and removal of membership which can be accomplished with the Add to List, Bulk Import Leads, or Remove from List REST Methods.

SOAP MethodREST Method(s)
getImportToListStatusBulk Import Leads
importToListAdd To List Bulk Import Leads
listOperationRemove From List

Activities

The SOAP API only supports retrieval of activities.

REST Documentation:

SOAP MethodREST Method(s)
getLeadActivityBulk Export Activities Get Lead Activities
getLeadChangesBulk Export Activities Get Lead Changes

Campaigns

REST Documentation:

The SOAP API only supports three use cases for smart campaigns: Triggering Leads to Qualify for a Requestable Smart Campaign, retrieving those Requestable Campaigns, and Scheduling a Future Run of a Smart Campaign.

SOAP MethodREST Method(s)
getCampaignsForSourceGet Smart Campaigns
requestCampaignRequest Campaign
scheduleCampaignSchedule Campaign