Skip to main content
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:
ConceptDescription
Custom object typeA schema you define that describes a category of objects (e.g., “Product”, “Subscription”)
Custom objectAn individual instance of a type (e.g., the “Pro Plan” subscription, or the “Enterprise Widget” product)
RelationshipA connection between a contact and a custom object
Relationship fieldsData 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:
SettingDescriptionRequirements
NameDisplay name for the object typeMust be unique across your instance
KeyUnique identifier used in Liquid and APIAlphanumeric and underscores only. Cannot be changed after creation
IconVisual identifier in the UISelected 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:
FieldDescriptionType
idUnique identifier in ConversionString
typeThe custom object type keyString
created_atWhen the object was first synced to ConversionDatetime
updated_atWhen the object was last modified in ConversionDatetime

​
Custom Fields

Custom fields are defined when creating or editing a custom object type. Each field requires:
SettingDescription
LabelDisplay name shown in the UI
KeyUnique identifier used in Liquid, queries, and API
Data typeThe 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:
FieldDescriptionExample Values
roleThe contact’s role or relationship type”Owner”, “Member”, “Viewer”
statusThe status of the relationship”Active”, “Inactive”
quantityQuantity associated with the relationship5, 100
started_atWhen the relationship began2025-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

Access a contact’s related objects through the objects namespace: 
{{ objects.product[0].name }}
{{ objects.subscription.first.plan_name }}
{{ objects.project[0].status }}
Each custom object type returns the 10 most recently created objects for that contact. Use indexes 0–9, or .first and .last as shortcuts.

​
Accessing Relationship Fields

Use _relationship to access fields on the relationship itself: 
{{ objects.product[0]._relationship.role }}
{{ objects.project.first._relationship.joined_date }}

​
Iterating Over Objects

{% for product in objects.product %}
  - {{ product.name }} ({{ product._relationship.quantity }} licenses)
{% 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

Liquid arrays return the 10 most recently created objects of each type (based on created_at). Use indexes 0–9 to access specific objects.
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.
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.