Tips and FAQ

Marketo's API is different than many other providers because the fields you want to monitor for changes or activities must be sent on each call. 

To accomplish this in the background, the Marketo element makes a few calls as part of the polling process:

1. GET /v1/activities/ (we include pagingtoken.json?sinceDatetime= where needed)
2. GET /objects/leads/metadata 
3. Using results from step 1 and step 2: /v1/activities/leadchanges.json?nextPageToken=<stepOneResults>&fields=<stepTwoResults>

If the leads object has too many fields or you want to only pull a certain list of fields, you can change the default by updating the instance configuration. In the instance configuration, make changes to default.select.fields.map. Here is an example:

{"leadChanges" : "mainPhone,id,mktoName,salutation,firstName,middleName,lastName,email,phone"} 

The following screenshot illustrates where this configuration should be placed in the UI.

The default page size for some endpoints (/activities, /campaigns, /companies, /contacts, /leads, /lists) in Marketo is 300 records. To avoid this limitation, the bulk functionality can be used. Marketo element supports two versions of bulk - Bulk v1 and Bulk v2. Bulk v1 is Cloud Elements Bulk Endpoints whereas Bulk v2 is Native Bulk Endpoints. 

Cloud Elements Bulk Endpoints

If you are using the bulk endpoints provided by Cloud Elements, we suggest the maximum number of records that can be requested in a query be 10,000, to help you avoid running into API rate limits. For example:

select * from leads limit 10000

Native Bulk Endpoints 

If you are using native bulk endpoints, you may want to include the to/from dates in the query. This filters the records by the date range specified. If the to/from dates aren't specified data will be retrieved for Now minus 31 days. Marketo also has a file size limit of 500MB/day.

603 Error ‘Access Denied’ - Authentication is successful but user doesn’t have sufficient permission to call this API. Additional permissions may need to be assigned to the user role.

A 603 Marketo error is thrown in the Marketo Admin Notifications if users attempt to make API calls to endpoints that they have not enabled Marketo API permissions for. If these errors are experienced then the Marketo account setup needs to be reviewed. It is important to note that if these errors are only seen for endpoints such as /companies/describe during authentication and access token refresh, then the cause of the 603 error may be due to the API calls that are made to build metadata when calling the Marketo /describe endpoints. If that is the case, then these 603 errors will not inherently cause issues for your users, but the Marketo account and permissions should still be reviewed.

Note that a 603 error is not passed through to us and is visible through the Marketo Admin Notifications only. If you need to find out which object was accessed that caused this 603 error with certainty, you will need to reach out to Marketo directly for assistance.

A 1018 Marketo error is thrown in the Marketo Admin Notifications if clients enable "read-only company" when it is not applicable.  The Marketo Company and Opportunity APIs are only available on instances that are not currently synced with a CRM such as Salesforce or MS Dynamics.  If a client's Marketo account is synced to a CRM they will need to un-check the 'company' and 'opportunity' API permissions in Marketo, and make updates to Company and Opportunity information through the CRM rather than the API.

Note that this 1018 error is not passed through to Cloud Elements and is only visible through the Marketo Admin Notifications.

Although Marketo supports webhooks, you might consider an alternative due to the API limit. You can use the GET /changed-contacts API instead.

The Marketo element does not support the GET /leads API commonly found in the Marketing hub. Instead, use GET /activity-types to find a relevant Lead Activity ID, and then use that ID in the where  CEQL parameter in GET /activities.

When using bulk to upload records, Marketo supports only upsert functionality (createOrUpdate). If you want to only create but not update records, include bulkUploadRecordSize in the metaData passed with the bulk request. Where bulkUploadRecordSize is the number of records (up to 300) in the upload. 

Requests that specify bulkUploadRecordSize can quickly use up API rate limits. See Should I be concerned about rate limits? for more.

Here's an example:

When working with Marketo bulk uploads (POST/bulk/{objectName} ),  the type of upload used is dependent on the metadata passed during the upload. By default, Marketo's native bulk endpoints do an upsert. In other words, if the record already exists it updates it and if it does not already exist, it inserts. To use the native bulk APIs for Marketo and use the upsert functionality a primaryKeyName (this is the field that will be looked at to see if the particular line is unique and identify if the process will be an insert or upsert) must be included in the JSON metadata.

If you would like to do an insert (without an upsert) then the Marketo's native bulk APIs can no longer be used. We have built our element  in such a way where you can still use bulk through our endpoints and we will handle making individual calls to insert into Marketo. To use this, you will need to change the metadata. The metadata still needs a primaryKeyName but a bulkUploadRecordSize of 2 or greater must also be added. If this piece is included, the job only inserts brand new data and errors on duplicate records. Please note that to utilize this functionality, our system makes individual calls to Marketo for each line in the CSV. It is important to be cognizant of this difference to avoid exceeding Marketo's API limits.

Question: Is there any error handling for failure to create duplicate leads in Marketo?

Answer: No. When an attempt to create a Lead through either POST /leads or a bulk upload fails due to duplicate field constraints, the response body includes no information to describe the offending record other than a generic provider message. Unfortunately, Marketo does not return the offending Lead ID when duplicates are encountered. Although not explicitly documented by Marketo, the Marketo documentation confirms that the examples of error 1005 ("Lead already exists") does NOT include a record/lead ID in the response and the duplicate records are simply 'skipped'.

Due to this Marketo limitation the /leads resource and bulk upload to the leads object do not provide error handling details in the response body when a failure to create duplicate leads is encountered.