How-To

How to Retrieve Every Custom Object

January 14, 2020 | by

We are often asked how to use Marketo’s API to get a list of all custom objects (COs). Querying for COs requires more than its name: some a priori knowledge about each CO is also required. The methods to get that knowledge may not be obvious since the API provides no method for querying it directly. As with many goals in Marketo Engage, Smart Lists provide an answer for COs linked to Persons (Leads). Smart Lists work differently with Companies and you’ll end up with a list of all Persons whose Companies are linked to the type of object for the filter so you may find it necessary to deduplicate companies depending on your goals.

Anytime a new Custom Object is approved, an associated filter is created. It will be named in the format “Has CO NAME“. In the example below, the custom object name is “Conference Track Subscription” and its filter is named “Has Conference Track Subscription“.

Once you have created the Smart List, you can retrieve the information necessary to query for associated COs using the custom objects endpoint. Export the list ensuring the linked field is included (either ID or email address). You can export using the Bulk Lead Extract API filtering by the smartListName or smartListId (1) filter or export from the UI. You’ll use each linked field value to query associated custom objects individually in the next step.

The custom object’s name is “Conference Track Subscription” in this example, and its API name is conferenceTrackSubscription_c. You’ll find the API name both in the UI as “API Name” and via the API as “name“.

Here it is in the UI:

Screen capture of custom object details in Marketo Engage UI
Admin | Marketo Custom Objects

And here’s a fragment returned by the List Custom Objects API endpoint:


To retrieve the custom objects associated one to one (1:1) or one to many (1:N) with the Persons in your Smart List, make a request like this:


In this example, this custom object is linked to Persons by the leadID field so the filter type is “leadID“. The filter values parameter is a comma-separated list of of the IDs taken from the Smart List export. The request may include as many filter values as you can fit in a single request URI: up to 8K characters. Requests exceeding this length will return a 414 HTTP-level error code. The response may be returned in more than one chunk. If so, moreResult will be true and a nextPageToken will be included. You will then need to page through the results until moreResult is false.

Here’s part of the result for the above API request:

You now have the values for each custom object directly associated with the Persons in your Smart List and beyond retrieving the values, you can use the marketoGUID to Update or Delete these objects.

For custom objects associated with Persons in a many to many relationship (N:N), the above technique will return the first level object which is the intermediary object connecting each Person to multiple second level COs. To retrieve those 2nd level COs, start a new set of queries for the 2nd level CO type by filtering on the link field and the values extracted from the 1st level intermediary object. For example, the above “Conference Track Subscription” object could have another level of objects representing sessions called “Session” which would probably be linked by the subscriptionID. The request to retrieve Sessions linked to the above Conference Track Subscriptions would then look like this:

 

Footnote

1) smartListName and smartListId filter types are unavailable for some subscriptions. If unavailable for your subscription, you will receive an error when calling the Create Export Lead Job endpoint (“1035, Unsupported filter type for target subscription”). Customers may contact Marketo Support to have this functionality enabled in their subscription.