> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conversion.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Objects

> Extend Conversion's data model with your own business entities and connect them to contacts.

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)   |

<Info>
  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.
</Info>

***

## 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](#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

<Info>
  **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.
</Info>

### 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

Access a contact's related objects through the `objects` namespace:

```liquid theme={null}
{{ 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:

```liquid theme={null}
{{ objects.product[0]._relationship.role }}
{{ objects.project.first._relationship.joined_date }}
```

### Iterating Over Objects

```liquid theme={null}
{% 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`:

```liquid theme={null}
{% 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 %}
```

<Info>
  For complete Liquid syntax and examples, see [Liquid Templating](/product-docs/liquid/overview).
</Info>

***

## 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

<Card title="Data Warehouse Integration" icon="database" href="/product-docs/sync/data-warehouse/overview">
  Learn how to connect your data warehouse and sync custom objects.
</Card>

***

## 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

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

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can a contact be related to multiple objects of the same type?">
    Yes. Relationships are many-to-many. A contact can be related to multiple products, multiple subscriptions, multiple projects, etc. Each relationship is independent and can have its own relationship field values.
  </Accordion>

  <Accordion title="Can an object be related to multiple contacts?">
    Yes. For example, a "Project" object might have relationships to an owner, several contributors, and multiple viewers. Each contact's relationship can have different field values (like `role`).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>