Custom Objects

Custom objects allow you to bring any external data into Conversion and connect it to your contacts. This enables you to trigger workflows based on custom data and segment your audience by relationships to business entities beyond contacts and companies.

Why Custom Objects?

Standard marketing automation data models center on contacts and companies. But your business likely has other important entities:

Products your customers have purchased
Subscriptions they’re enrolled in
Projects they’re collaborating on
Courses they’ve completed
Support tickets they’ve submitted
Contracts they’ve signed

Custom objects let you define these entities, sync them from your data warehouse, and use them throughout Conversion for segmentation and personalization.

Key Concepts

Before diving in, here are the core concepts you’ll work with:

Concept	Description
Custom object type	A schema you define that describes a category of objects (e.g., “Product”, “Subscription”)
Custom object	An individual instance of a type (e.g., the “Pro Plan” subscription, or the “Enterprise Widget” product)
Relationship	A connection between a contact and a custom object
Relationship fields	Data stored on the relationship itself, describing the nature of the connection (e.g., role, quantity)

Custom objects are contact-centric. While objects exist independently, they’re accessed and used in the context of their relationships to contacts. A contact can be related to many objects of the same type, and an object can be related to many contacts.

Custom Object Types

A custom object type defines the schema for a category of objects. Before syncing any data, you create the type that describes what fields your objects will have.

Creating a Custom Object Type

Navigate to Settings → Custom Objects to create a new type. Each type requires:

Setting	Description	Requirements
Name	Display name for the object type	Must be unique across your instance
Key	Unique identifier used in Liquid and API	Alphanumeric and underscores only. Cannot be changed after creation
Icon	Visual identifier in the UI	Selected from available icon set

After creating the type, you’ll define its fields (see Fields below).

Fields

Custom objects have two categories of fields: reserved fields that Conversion manages automatically, and custom fields that you define.

Reserved Fields

Every custom object includes these system-managed fields:

Field	Description	Type
`id`	Unique identifier in Conversion	String
`type`	The custom object type key	String
`created_at`	When the object was first synced to Conversion	Datetime
`updated_at`	When the object was last modified in Conversion	Datetime

Custom Fields

Custom fields are defined when creating or editing a custom object type. Each field requires:

Setting	Description
Label	Display name shown in the UI
Key	Unique identifier used in Liquid, queries, and API
Data type	The field’s data type

Relationships

Relationships connect contacts to custom objects. They enable many-to-many associations: a contact can be related to multiple objects of the same type, and an object can be related to multiple contacts.

How Relationships Work

A relationship is created when your data sync establishes a connection between a contact and a custom object. Each relationship:

Links exactly one contact to exactly one custom object
Can carry its own field values (relationship fields)
Is accessed from the contact’s perspective in Liquid and segmentation

Example: A “Project” custom object might have relationships to multiple contacts. Each relationship could have fields like role (e.g., “Owner”, “Contributor”) and joined_date. This lets you personalize messaging based on not just which project a contact is on, but how they’re involved.

Relationship Fields

Relationship fields store data about the connection itself—not the contact or the object. Common examples:

Field	Description	Example Values
`role`	The contact’s role or relationship type	”Owner”, “Member”, “Viewer”
`status`	The status of the relationship	”Active”, “Inactive”
`quantity`	Quantity associated with the relationship	5, 100
`started_at`	When the relationship began	2025-01-15T00:00:00Z

Unlike custom object fields which have defined schemas, relationship fields are flexible and inferred from your sync data.

Segmentation

You can filter contacts based on their relationships to custom objects in audiences and workflow filters. For example, you could filter for Contacts linked to a “Subscription” where status = “Active” and relationship role = “Owner”.

Workflow Triggers

Custom objects can trigger workflows when objects or relationships change. Common triggers include:

Object Updated
Relationship Added
Relationship Removed
Relationship Updated

Using Custom Objects in Liquid

Custom objects are available in emails, workflow nodes, and anywhere else Liquid is supported.

Accessing Objects

Related records appear directly on the object that holds the relationship, addressed by the relationship field’s key:

{{ contact.products[0].name }}
{{ contact.subscription.plan_name }}
{{ company.projects[0].status }}

A to-one relationship resolves to a single record; a to-many relationship returns up to 10 records. Use indexes 0–9, or .first and .last as shortcuts.

Iterating Over Objects

{% for product in contact.products %}
  - {{ product.name }}
{% endfor %}

Trigger Context

When a workflow is triggered by a custom object event, the triggering object is available via trigger.object:

{% if trigger.type == "object_updated" %}
  {{ trigger.object.name }} was updated.
  
  {% if trigger.object._changed.status %}
    Status changed from {{ trigger.object._previous.status }} to {{ trigger.object.status }}.
  {% endif %}
{% endif %}

For complete Liquid syntax and examples, see Liquid Templating.

Syncing Custom Objects

Custom objects are synced from external data sources. Conversion supports:

Data warehouse sync — Connect your data warehouse and map tables to custom object types
Salesforce custom objects — Sync custom objects from Salesforce

Data Warehouse Integration

Learn how to connect your data warehouse and sync custom objects.

Deleting a Custom Object Type

Deleting a custom object type:

Removes all objects of that type from Conversion
Removes all relationships to those objects
Invalidates any workflows or audiences referencing that type
Cannot be undone

Review dependencies before deleting. Workflows and audiences referencing deleted custom object types will need to be updated.

Frequently Asked Questions

How many objects can I access in Liquid?

Liquid arrays return the 10 most recently created objects of each type (based on created_at). Use indexes 0–9 to access specific objects.

What's the difference between object fields and relationship fields?

Object fields describe the object itself (e.g., a product’s name, price, or category). Relationship fields describe the connection between a contact and an object (e.g., the contact’s role on a project, or the quantity they purchased). The same object can have different relationship field values for different contacts.

Can I change a field's data type after creation?

No. Field keys and data types are immutable after creation. To change a data type, create a new field with the correct type and update your sync to populate it.

Records

Emails

Workflows

Audiences

Forms

Content

Campaigns

Data Syncing

Unified Query Engine

Folders

Liquid

Tracking

Workspace Settings

GDPR

Why Custom Objects?

Key Concepts

Custom Object Types

Creating a Custom Object Type

Fields

Reserved Fields

Custom Fields

Relationships

How Relationships Work

Relationship Fields

Segmentation

Workflow Triggers

Using Custom Objects in Liquid

Accessing Objects

Iterating Over Objects

Trigger Context

Syncing Custom Objects

Data Warehouse Integration

Deleting a Custom Object Type

Frequently Asked Questions

​Why Custom Objects?

​Key Concepts

​Custom Object Types

​Creating a Custom Object Type

​Fields

​Reserved Fields

​Custom Fields

​Relationships

​How Relationships Work

​Relationship Fields

​Segmentation

​Workflow Triggers

​Using Custom Objects in Liquid

​Accessing Objects

​Iterating Over Objects

​Trigger Context

​Syncing Custom Objects

Data Warehouse Integration

​Deleting a Custom Object Type

​Frequently Asked Questions

Why Custom Objects?

Key Concepts

Custom Object Types

Creating a Custom Object Type

Fields

Reserved Fields

Custom Fields

Relationships

How Relationships Work

Relationship Fields

Segmentation

Workflow Triggers

Using Custom Objects in Liquid

Accessing Objects

Iterating Over Objects

Trigger Context

Syncing Custom Objects

Deleting a Custom Object Type

Frequently Asked Questions