Get a demoLog inAcademyDevelopers

Custom Objects

Custom Objects let you extend your data model beyond standard objects like Contacts and Companies. You can define and store your own data structures — such as bookings, accounts, subscriptions — and then use them in segmentation and personalization

This article walks you through what Custom Objects are, how to create them, and how to manage them effectively.

What are custom objects?

Custom Objects are user-defined data tables that allow you to model business-specific entities within the platform. They can be related to one or more other standard (Contacts, Companies) or other custom objects.

For example:

  • A travel platform might create a Booking object with fields like booking_id, destination, and status.

  • An e-commerce brand might create a Loyalty Card object with fields like card_id, category, and balance.

  • A subscription service might create a Plan object with fields like plan_name and renewal_date.

  • A finance company might create an Account object with fields like Account Type, Balance, Status

Once defined, you can:

  • Import data into the object using APIs

  • Link it to contacts or other objects (e.g., through defined one-to-many relationships)

  • Use it in segments, Journey triggers and personalization

Create a Custom Object Type

  • Go to Marketing > Settings > CRM > + New Object Types in the navigation menu.

  • Click ➕ New Object Types. This will open the custom object creation form

  • Define your object details:

    • Display Name: (e.g., Accounts) - This is used to display in the navigation UI of the CRM

    • Object's display name - Select an attribute which shows as its name when referenced in UI in other objects e.g. Account Name . You can select it later after defining attributes.

    • Name: e.g. accounts - An internal name which may be referenced in the API

    • Description (optional) to explain the purpose of the object.

Define your object attributes:

  • Display Name: (e.g., Account Name) - This is used to display the name of the object attribute in the UI

  • Description (optional) to explain the purpose of the object.

  • Name: (e.g., account_name) - Internal name of the object attribute to be referenced in the API

  • Type: e.g. Text - Select the type of data to be stored such as Text, Dropdown, Number, True/False, Date, Relation etc.

  • Required: Select if the attribute is required for creating an object record

We support a variety of data types and each have their own configurations.

Text

In addition to the common fields, you can define if text field has

  • Contains PII

  • Mode: Has multiple values or descriptive multiline text

Dropdown

In addition to the common fields, you can define if text field has

  • Options: UI Labels and internal names for API

  • Has multiple values

Numbers

In addition to the common fields, you can define if text field has

  • Has decimal places and how many

Date and Date & Time

You can select based on whether your attribute will accept only date (day, month, year) or timestamp as well

True/False

You can select whether your data type is boolean and will accept only True/False values

Link

This is generally used to capture any web links and you can select if it

  • Contains PII

  • Has multiple values

Email Address or Phone Number

This is generally used to capture email address and phone numbers. You can define if this attribute

  • Contains PII

  • Has multiple values

Unique ID

This attribute can be used to define a unique ID for the custom object record.

Relation

This is a very important type of attribute which helps to define a relation with any other standard or custom objects.

  • You can define if the relation is unique mapping

  • You can select the Object type which is the object to which it is related. For example. if you want one to many relation with contacts, you can select Contacts here. In this case Accounts custom object can have multiple records associated to a contact

  • Relation Name: This is the name of the related object which will be shown on the Object type selected. For example, in this case, the Contacts page will show the tab for Accounts to view any related accounts to it.

Viewing Custom Objects

Once a custom object is created, you will see it in the navigation menu under Settings > CRM, under Object Types and you can edit and manage them.

You will also start seeing the object record views under CRM navigation menu in addition to the standard objects. This would be a list of the object records for this object type.

Creating Custom Object Records

Once your custom object type is created, you can start created records for it

  • Navigate to CRM > Your custom object

  • Click on Create object

  • You can also navigate to Settings by clicking on Object type settings

  • The Create object form will show the attributes you have defined when building the object type

  • Any attributes of Type = Relation will allow you to associate the object record with other object records such as you can select a contact to associate this object record with.

To create and update custom object records at scale, you can use the Custom objects API.

Viewing Related Objects

When you create a custom object record and associate it with another object record (custom or standard object), you will start seeing it in the respective details page of the object.

For example, if Accounts custom object is associated to Contacts, you will start seeing Accounts tab on the Contacts detail page

Using custom object data

Once you have custom object records created and associated to related objects, you may now want to start using them for segmentation, journey triggers and personalization.

Segmentation

You can start using your custom objects for segmentation of contacts if you have associated them to Contacts objects as follows:

  • Create a segment by clicking on Properties of related object

  • Select the object type

  • Select any further object properties to filter on

  • If you want to match different object property filters to the same object record associated to the contact, you can add object property filters as AND within the same condition.

  • If you want to match different object property filters to the different object records associated to the contact, you can add object property filters as AND with separate conditions

Journey Triggers

You can use custom object record updates as journey triggers for specific object types

The following Journey triggers are available:

  • Related Object Created: When an object record related to contact is created

  • Related Object Updated: When an object record related to contact is updated

  • Related Object Deleted: When an object record related to contact is deleted

  • Added to Object: When a contact is associated to a custom object record

  • Removed from Object: When a contact is removed from a custom object record

Once the trigger type is selected, you can then select the object type:

You can also add entry/exit conditions or even condition steps based on the properties of the custom object record which causes the journey to trigger

Note that if there are multiple custom object associated with the contact each update will cause the journey to trigger separately. The journey will not trigger again if there is already an existing run for the same contact.

To add conditions based on the custom object properties you need to select:

  • Properties about event

    • Select the custom object property of the selected object type in the trigger

    • Add the operator and the matching values

Personalization

You can also personalize your content based on the values of the object attributes. For this you need to:

  • First define a custom variable in the template

  • Use that variable in the template

  • Add the template to journey Send message step

  • Map the template variable to Events > Select the object property

  • Give a default value

Note that you can only personalize content for Journeys based on the template variables or using liquid in email templates as event.objectEvent.body.accountStatus|default:"status"

The value of the variable will be based on the custom object record related to the contact which triggered the journey.

You cannot personalize Campaign content using custom object property values as one contact can have multiple custom object records.

Last updated

Was this helpful?