Custom Objects

Custom Object Endpoint Reference

Marketo allows users to define custom objects which are related either to lead records, or account records.  For information on defining these, please see this article.

Custom Objects are unavailable for some Marketo subscription types.  If you don’t have access to this feature, please, speak to your account manager.


In addition to the standard describe, query, update, and delete calls available for lead database objects, Custom Objects have a list call available.  Calling this endpoint will return a response with a list of custom objects available in the destination instance, along with additional metadata about the objects.

The response will give a list of the relationships present on each object.  A relationship will have a field member which indicates the field on the object which holds the link value, a type member which indicates if the relationship is to a parent or a child type object, and a relatedTo object indicating the name of the related object, and the link field on that object.


The describe call for custom objects follows the same pattern as that of Opportunities and Companies, with the addition of the relationships array in the response and a name path parameter in the URI which takes the name of the custom object type to be described.  Like the list call, this will list any relationships that are available for this custom object type.


Querying custom objects is slightly different from other Lead Database APIs, and takes name path parameter like describe.  For a normal filterType parameters, the query is a simple GET like queries for other types of records, and requires a filterType and filterValues.  It will optionally accept fields, batchSize, and nextPageToken parameters.  When requesting a list of fields, if a particular field is requested, but not returned, the value is implied to be null.

Alternatively, when querying with compound keys, the API behaves like the Opportunity Roles API, accepting a POST with a JSON body.  The JSON body may have the same members as a GET query, except for filterValues.  Instead of filter values, there is an input array which takes objects which contain a member named for each of the object type’s dedupeFields.

Create and Update

To create or update records, custom objects follow the standard pattern for lead database objects, and is largely based on the information available in the description of the object type.  In an example car object, there is just one dedupe field, vin.  In order to update or create records when using dedupeFields mode, each record in our input array needs to include at least a vin field.

When performing updates via idField mode, the idField will always be marketoGUID, so each record will always require a marketoGUID field.  Remember that idField is only valid for the updateOnly action type, as this field is always system managed.  Your response will include the status of each individual record in the result array, and either a marketoGUID or a reasons array depending on whether or not the operation was successful for an individual record.


Deleting records is very straightforward.  Just select your deleteBy mode, either idField or dedupeFields, and include the corresponding fields in each of the records in your input array.  A maximum of 300 records per call is allowed.

Like updating, your result will contain a status for each individual record, and either a marketoGUID or a reasons array depending on whether the delete was successful.