Custom Objects

Custom Object Endpoint Reference

Marketo allows users to define Marketo Custom Objects which are related to Marketo Standard Objects (Leads, Companies) or other Marketo Custom Objects.  Marketo Custom Objects can be created using the Marketo UI as described here, or by using the Custom Object Metadata API as described below.

Note that the appropriate Marketo subscription type is required to access the Custom Object Metadata API.  Please consult your CSM for details.

 

Contents
  1. List
  2. Describe
  3. Query
  4. Create and Update
  5. Delete
  6. Bulk Import / Bulk Extract
  7. Custom Object Types
    1. Query Type
      1. Describe Type
      2. List Types
    2. Create and Update Type
      1. Create Type
      2. Update Type
    3. Approval of Type
      1. Approve Type
      2. Discard Type
      3. Delete Type
  8. Custom Object Fields
    1. Add Fields
      1. One-to-Many Relationship
      2. Many-to-Many Relationship
    2. Update Field
    3. Delete Fields
    4. List Field Data Types
  9. List Linkable Custom Objects
  10. Get Custom Object Dependent Assets
  11. Timeouts

List

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.

Describe

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.

Query

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

Use the Sync Custom Objects endpoint to create or update custom objects, you can specify the operation using the action parameter.  Up to 300 records can be created or updated in one call.  The values used in the input array are largely based on the information returned by the Describe Custom Objects endpoint.

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.

Delete

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.

Custom Object Types

The Custom Object Metadata API allows you to remotely manage custom object schemas.  The API allows you to create a new Custom Object Type or modify an existing one.  Once the Custom Object Type has been created or modified, it must be approved for use.  For more information about custom objects, please see product documentation here.

  • Custom object types created by the API may not be modified using the Marketo UI
  • The maximum number of custom objects types allowed is 10
  • The maximum number of custom object fields allowed is 50 per type
  • Custom object type API Names and Display Names may contain alphanumeric characters and underscore “_”

Query Type

There are two ways to retrieve custom object type metadata: Describe Custom Object Type, which returns  the record for a single custom object type, and is filterable by approval state, and List Custom Object Types, which returns a list of all custom object types in the subscription, and is filterable by name and by approval state.

Describe Type

The Describe Custom Object Type endpoint returns metadata for a single custom object type.

The required apiName path parameter is the API name of the custom object type that is described.  If an approved version exists, it is returned.  Otherwise the draft version is returned.  The optional state parameter is used to specify the version to return: draft, approved, or approvedWithDraft.

Here we can to see the following attributes:

  • Metadata: state, displayName, description, apiName, idField, createdAt, updatedAt, dedupeFields, searchableFields, relationships
  • Standard fields: marketoGUID, createdAt, updatedAt
  • Custom fields leadId, vin, make,  model, year

List Types

The List Custom Object Types endpoint returns metadata for all custom object types available in the destination instance.  Note that this endpoint is similar to List Custom Objects, but is more comprehensive and includes additional metadata such as state, relationships, and fields.

If an approved version exists, it is returned.  Otherwise the draft version is returned.  The optional state parameter is used to specify the version of the custom object type to return: draft, approved, or approvedWithDraft.  The optional names parameter is used to specify specific names of custom object types to return; it is structured as a comma separated list of API names.

Create and Update Type

Create Type

The Sync Custom Object Type endpoint is used to create or update a custom object type.  The record operation to perform is controlled by the optional action attribute which can be createOnly, createOrUpdate, or updateOnly.  Default setting is createOrUpdate.

The displayName and apiName attributes are required, except when using updateOnly as your action.   Both must be unique to avoid collisions with customer-provisioned types.  If you are a LaunchPoint partner, you should prepend a representative namespace to these names.  For apiName, the convention is to use lowercase or camelCase to help distinguish between other text strings.

The optional pluralName attribute specifies the plural form of displayName.  The optional description attribute is used to describe the custom object type.  The optional showInLeadDetail boolean attribute is used to enable viewing custom object data within the Lead Database page of the Marketo UI.  Default setting is false.

Be careful when naming custom objects. When creating a new custom object, it is recommended that you prefix the name with a string that indicates your company name (alphanumeric or underscore permitted). This makes the custom object easily searchable in the MLM UI, and also helps unsure that the name is unique.

Here is an example of creating a new custom object type with API  Name “transaction”.

And here is a subsequent call to describe the newly created type.

Here we can see the following custom object-related data:

  • Metadata: state, displayName, description, apiName, idField, createdAt, updatedAt, dedupeFields, searchableFields, relationships
  • Standard fields: marketoGUID, createdAt, updatedAt

Update Type

Here is an example of updating the Description for an existing type whose API Name is “transaction”.  The apiName attribute is required.  Here we will assume that the type already exists and use updateOnly for the optional action attribute.

Approval of Type

Custom object types must be approved before they can be used.  When a new custom object type is created using Sync Custom Object Type endpoint, it is created as a draft version.  When you are done adding custom fields, you must approve the draft version.  This creates an approved version and deletes the draft version.

When an existing custom object type is modified by using Sync Custom Object Type endpoint, or by using one of Add/Update/Delete Custom Object Type Field endpoints,  a draft version is created.  All modifications to the type or to its fields impact the draft version only.  When you are done modifying, you must approve the draft version.  This replaces the approved version with the draft version, and deletes the draft version.

For more information about custom object approval, please see product documentation here.

Once a custom object type is approved, you cannot:

  • Update the displayName or apiName
  • Add or remove a link field
  • Add or remove a dedupe field

For these reasons, it is important to carefully think through the schema and naming convention that you plan to use.

Approve Type

Use the Approve Custom Object Type endpoint to publish a draft version as the new approved version.  apiName is the only required parameter as a path parameter.  A type cannot be approved unless it is in draft state, and satisfies a set of validation rules described here.

Discard Type

Use the Discard Custom Object Type Draft endpoint to delete a draft version.  apiName is the only required parameter as a path parameter.  A type must be in draft state to be discarded.  i.e. an approved type cannot be discarded.

Delete Type

Use the Delete Custom Object Type endpoint to delete an approved version.  apiName is the only required parameter as a path parameter.  Note that this is a destructive operation; it cannot be undone.  A type cannot be deleted unless it has been removed from use by any assets, such as triggers or filters.  The Get Custom Object Dependent Assets endpoint can be used to retrieve a list of dependent assets for a given type.

Custom Object Fields

By default, all custom object types contain the following standard fields:

  • Marketo GUID – Unique identifier for custom object type
  • Created At – Datetime when custom object type was created
  • Updated At – Datetime when custom object type was last updated

You are free to add/change/delete custom fields using the endpoints described below.

  • The maximum number of fields allowed is 50
  • At least 1 dedupe field is required, a maximum of 3 are allowed
  • Field API Names and Display Names may contain alphanumeric characters and underscore “_”

For more information about custom object fields, please see product documentation here.

Add Fields

The Add Custom Object Type Fields endpoint allows you to add one or more fields to your custom object.  The request body contains an input array with one or more elements.  Each element is a JSON object with attributes that describe a field.

The required name attribute is the API name of the field and must be unique to the custom object.   The convention is to use lowercase or camelCase to help distinguish between other text strings.

The required displayName attribute is the human readable name of the field and must be unique to the custom object.

The required dataType attribute is the data type of the field.  A  list of permissible data types can be obtained by calling the Get Custom Object Type Field Data Types endpoint.  Custom objects can contain fields with data type “link”.  Link fields are used used to establish relationships between custom objects and other object types in the system, e.g. Lead, Company.  More information on link fields can be found here.

The optional description attribute is the description of the field.

The optional isDedupeField boolean attribute specifies whether the field is used for deduplication during custom object update operations.  Default setting is false.  For one-to-many relationships, a dedupe field is required.

The optional relatedTo object attribute specifies a link field.  For one-to-many relationships, this object contains a name attribute which is the “link object” or parent object to link to, and a field attribute which is the “link field,”  or the field within the parent object to use as key attribute.  Call the Get Custom Object Linkable Objects endpoint to retrieve a list of permissible link objects.  For more information on link fields, see product documentation here.

A custom object cannot link to another custom object that has an existing link field.

One-To-Many Relationship

For a one-to-many custom object structure, use a link field in a custom object to connect it to a standard object: Lead or Company.

Using the car owner example from Marketo product documentation here, we create a custom object that contains car-related information to connect with Leads.

Here are the steps:

  1. Create a Car object
  2. Add fields to Car object: dedupe on VIN, link to Lead/Lead ID
  3. Approve Car object

First, let’s create the custom object type to contain car-specific information.

Now, let’s add fields to the Car custom object type.  We use a link field to specify the both the object and the field to connect to.  In this case the link object is Lead, and the link field is ID.  We will use a string field for deduplication (VIN).  We will add three more fields to store additional Car attributes (Make, Model, Year).

Finally, we need to approve the custom object type.

Many-To-Many Relationship

Many-to-many relationships are represented using a “bridge,” or intermediary, custom object in between a standard custom object, like Lead or Company, and an “edge” custom object.

The edge object is the primary entity containing descriptive attributes (fields).

The bridge object contains the data to resolve the object relationships by using 2 link fields.  One link field points back to the parent standard object just like in a  one-to-many relationship configuration.  The other link field points to the edge object, which is a custom object with no links.  The bridge object may also contain descriptive attributes (fields).

Using the college course enrollment example from Marketo product documentation here, we create an edge custom object to contain course-related information, and an enrollment bridge object used to connect Courses with Leads.

Here are the steps:

  1. Create a Course edge object
  2. Add fields to Course: dedupe on Course ID
  3. Approve Course
  4. Create an Enrollment bridge object
  5. Add fields to Enrollment: dedupe on Enrollment ID, link to Course/Course ID field and link to Lead/Lead ID
  6. Approve Enrollment

First, let’s create the edge object type to contain course-specific information.

Next, let’s add custom fields to the edge object type.  In this example we will add the following four custom fields to model a college course: Course ID, Course Instructor, Course Location, Course Name.  Note that we are designating Course ID as our dedupe field, since at least one dedupe field is required.

Now we need to approve the edge object type so that we can reference it later when linking to the bridge object type.  Note that custom object types must be approved to be selectable as a link object.

We’re done creating the edge object!  Now let’s move on to create the bridge object type to contain enrollment-specific information.

Next, let’s add custom fields to the bridge object type.  We need to add two link fields, one linking to the Lead object, and another linking to the  Course object that we just created.  To link to the Lead object, we’ll use the Lead Id field.  To link to the Course object, we’ll use the Course Id field.  We will add Enrollment ID unique identifier as our dedupe field since at least one dedupe field is required.  Finally, we will add a Grade field to track how the student did.

Finally, we need to approve the bridge object.

Now we’re ready to populate custom object records!  You can do this programmatically by using Sync Custom Object, or Bulk Custom Object Import.  Alternatively, you can use Marketo UI functionality Import Custom Object Data.

Update Field

The Update Custom Object Type Field endpoint allows you to update a field in your draft custom object.  The required path parameter apiName is the API name of the custom object type.  The required path parameter fieldAPIName is the API name of the custom object type field.  The request body contains a JSON object containing key/value pairs that specify the field attributes to update.

Delete Fields

The Delete Custom Object Type Fields endpoint allows you to delete one or more fields from your custom object.  The required path parameter apiName is the API name of the custom object type.  The request body contains JSON object with an input array with one or more elements.  Each element is a JSON object with a name attribute that specifies the API name of the field to delete.

List Field Data Types

The Get Custom Object Type Field Data Types endpoint returns the list of all permissible field data types.  This is useful when modeling your custom object type to identify the custom field data types that are supported.

List Linkable Custom Objects

The Get Custom Object Linkable Objects endpoint returns a list of all permissible link objects, and their link fields.  The list will contain Standard Objects (Lead, Company), and any Custom Objects that have been created in the instance.

Get Custom Object Dependent Assets

The Get Custom Object Dependent Assets endpoint returns a list of dependent assets of a custom object type, including their in-instance location.  This is useful when removing an integration and you need to identify everywhere that a custom object type is in use.

 

Timeouts

  • Custom Objects endpoints have a timeout of 30s unless noted below
    • Sync Custom Objects: 120s 
    • Delete Custom Objects: 60s