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

> Model your own business data, such as subscriptions, products, or projects, as records in Conversion and link them to contacts, companies, and opportunities.

A custom object is a record type you define for data that doesn't fit contacts, companies, or opportunities. Each custom object has its own fields and its own records page. Relationship fields link its records to contacts, companies, opportunities, or other custom objects, so you can filter contacts by their related records, trigger workflows when those records change, and use their values in emails.

Common examples:

* **Subscriptions** a company pays for
* **Orders** or **products** a contact has purchased
* **Projects** or **workspaces** in your product
* **Support tickets**
* **Pricing tiers** or other lookup tables

> [!NOTE]
>
> Custom objects are not enabled for every workspace. If you don't see the **Custom objects** section on the [Objects](/product-docs/workspace-settings/objects/overview.md) settings page, contact Conversion.

***

## Key concepts

| Concept | Description |
| :- | :- |
| **Custom object** | A record type you define, such as *Subscription*. It has a label, a plural label, a key, an icon, and fields. |
| **Record** | One instance of a custom object, such as one company's subscription. |
| **Field** | A value stored on each record, such as `plan` or `renews_at`. |
| **Primary field** | The field whose value names each record across Conversion. |
| **Relationship field** | A field whose value is a link to one record of another object. |

***

## How relationships work

A relationship field lives on one object and holds one related record. When you create it, Conversion adds a matching field to each related object that lists every record pointing at it.

For example, a **Company** relationship field on *Subscriptions* links each subscription to one company. Each company gets a matching **Subscriptions** field that lists all of its subscriptions.

| Side | Holds | Example |
| :- | :- | :- |
| The field you create | One related record | A subscription's **Company** |
| The matching field on the related object | Every record that points at it | A company's **Subscriptions** |

* Each relationship is one-to-many: a subscription has one company, and a company can have many subscriptions.
* Relationship fields can be created on contacts, companies, and custom objects. They can point at contacts, companies, opportunities, or custom objects.
* One relationship field can point at several objects. For example, a **Customer** field on *Orders* can link to either a contact or a company.
* In the app, you can link and unlink records from either side. Syncs and the API set the value only on the field you created. The matching field is read-only to them.

To create relationship fields, see [Relationship fields](/product-docs/workspace-settings/objects/fields.md#relationship-fields).

### Storing details about a link

A relationship has no fields of its own. To record details about a link, such as a contact's role on a project, or to link many records to many records, create a custom object for the link itself.

For example, a *Project member* custom object with:

* A **Contact** relationship field to Contacts
* A **Project** relationship field to *Projects*
* A **Role** string field

Each contact then has a list of project members, and each project member names its project and the contact's role on it.

***

## Set up a custom object

### Before you begin

* Editor access or higher to create records in Conversion
* To sync from Salesforce: a connected Salesforce account and the Salesforce object you want to sync

### Steps

1. [Create the custom object](/product-docs/workspace-settings/objects/overview.md#creating-a-custom-object) in **Settings → Objects**. To sync it from Salesforce, choose **Sync** and pick the Salesforce object. You can't add or change the Salesforce object later.
2. On the object's **Fields** tab, [create its fields](/product-docs/workspace-settings/objects/fields.md#creating-a-field). Salesforce-synced objects get their fields automatically.
3. Create [relationship fields](/product-docs/workspace-settings/objects/fields.md#relationship-fields) to link records to contacts, companies, or other objects.
4. On the object's **Overview** tab, choose the **Primary field**. Conversion uses its value as each record's name. Salesforce-synced objects start with the Salesforce object's name field.
5. Load records from one of the [sources below](#getting-records-into-conversion).

Onboarding with Conversion? Let your Deployment Strategist know when this is done and we'll check it on our end.

***

## Getting records into Conversion

| Source | Records are matched by | Learn more |
| :- | :- | :- |
| **Salesforce** | Salesforce ID | [Syncing with Salesforce](#syncing-with-salesforce) |
| **Data warehouse** | The `object_id` column | [Custom Objects](/product-docs/sync/data-warehouse/overview.md#custom-objects) |
| **API** | `objectId` | [Batch Upsert Custom Object Records](/api-reference/batch-upsert-custom-object-records.md) |
| **Manually** | Not applicable | [Creating a record](#creating-a-record) |

Data warehouse syncs and the API can link a record to one that doesn't exist yet. The link stays pending and completes if the related record arrives within a few days. See [Custom Objects with Relationships](/product-docs/sync/data-warehouse/overview.md#custom-objects-with-relationships).

### Syncing with Salesforce

A custom object linked to a Salesforce object syncs records from Salesforce into Conversion. You can link it to a standard or custom Salesforce object, except the objects Conversion already syncs: Account, Campaign, Campaign Member, Contact, Lead, Opportunity, and Opportunity Contact Role.

* **Fields:** when you create the custom object, Conversion creates a field for each field on the Salesforce object and sets the primary field to the Salesforce object's name field. Fields added to the Salesforce object later are added on the next sync. This differs from contacts and companies, where [each custom field is mapped by hand](/product-docs/sync/salesforce/custom-fields.md).
* **Direction:** records sync one way, from Salesforce into Conversion, matched by Salesforce ID. Their field values are read-only in Conversion, and you can't create records in Conversion for a Salesforce-synced object.
* **Deletes:** records deleted in Salesforce are deleted in Conversion. Deleting a record in Conversion doesn't delete it in Salesforce.
* **Lookup fields:** a lookup to an object Conversion syncs (contacts, leads, accounts, opportunities, or another synced custom object) isn't imported on its own. Create a relationship field to the matching Conversion object, then [link it to the lookup field](/product-docs/workspace-settings/objects/fields.md#linking-fields-to-salesforce). Lookups to objects Conversion doesn't sync are imported as text fields.
* **Excluding records:** on the object's **Overview** tab, expand the Salesforce object in the **Sync** section and choose a checkbox field under **Exclude ... by field** (for example, **Exclude Subscriptions by field**). Records with that field checked don't sync. Only admins can change this.

***

## Viewing records

Each custom object appears under **Records** in the sidebar, after Contacts, Companies, and Opportunities, sorted by plural label. Click it to open its records list.

The list works like the other records lists:

* **Views:** save filters and columns as named views. New columns are opt-in: the default view shows the primary field.
* **Filter:** filter records by any of their fields, including fields on related records. See [Filtering by related records](#filtering-by-related-records).
* **Columns:** choose, reorder, rename, and resize columns.
* **Search:** searches the primary field. The search is hidden when the object has no primary field.

By default, records are sorted by **Created at**, newest first. Editors can change field values directly in the table, except on Salesforce-synced objects.

### Creating a record

1. Open the custom object from the sidebar.
2. Click **New** followed by the object's label, for example **New subscription**.
3. Fill in the fields. The primary field is required.
4. Click **Create**.

The **New** button appears only for editors and above, and not on Salesforce-synced objects.

### The record page

Click a record's name to open it in a side panel, or expand it to a full page. The **Fields** card lists every field on the record, including relationship fields on both sides. Use **Hide empty fields** to show only fields with values.

Each related record appears as a chip. Click it to open that record. To change a link, edit the relationship field's value:

* On the field you created, pick one record in **Edit related record**.
* On the matching field, check or uncheck records in **Edit related records**.

Relationship fields also appear on the **Details** tab of contact and company records, and as columns in the contacts and companies lists.

### Deleting a record

Open the record's options menu and choose **Delete**, then click **Confirm and delete**. Deleting a record removes its field values and clears every relationship field that points at it. It can't be undone.

***

## Using custom objects

### Filtering by related records

Filters can check related records in audiences, workflow conditions, records list views, and [lead scoring](/product-docs/scoring/rules.md) fit rules. Audiences always contain contacts, not custom object records.

In a condition's field picker, choose a relationship field to move to the related object, then choose one of its fields. A path can cross up to three relationships, for example **Company** → **Subscriptions** → **Plan**. Add more conditions on the related records with **Add filter** under the related object's fields section, for example **Subscription fields**.

When the condition compares a relationship field itself:

| Field | Operators |
| :- | :- |
| The field you created | **is**, **is not**, **is any of**, **is not any of**, **is set**, **is not set** |
| The matching field | **contains**, **does not contain**, **contains any of**, **does not contain any of**, **has any**, **has none** |

For the full filter reference, see [Unified Query Engine](/product-docs/unified-query-engine/overview.md).

### Triggering workflows

Use the **Field is changed** trigger. In **Field**, start from the contact, choose the relationship that leads to the custom object, and pick the field to watch. The workflow runs for the contacts the changed record reaches through that path.

For a regular field, set an optional **Old value** and **New value**. For a relationship field, choose the **Change**:

| Change | Runs when |
| :- | :- |
| **A record is linked** | The field gets a record, whether it was empty or already set. |
| **A record is unlinked** | The field is cleared. |
| **A record is replaced** | One linked record is swapped for another. |

Narrow which linked records count with **Linked record** or **Unlinked record**, and filter on the related records' fields with **Add filter**.

Workflows don't trigger when a custom object record is created or deleted, and they can't create or edit custom object records. The [Update field](/product-docs/workflows/nodes/update-field.md) node can set a contact's relationship field to a record.

### Personalizing with Liquid

Related records are available in emails and anywhere else Liquid is supported, through the relationship field's key:

```liquid theme={null}
{% for subscription in company.subscriptions %}
  {{ subscription.plan }} renews {{ subscription.renews_at | date: "%b %-d" }}
{% endfor %}
```

A field you created returns one record. A matching field returns up to 10 records, newest first. Use record filters to choose which records you get, or `objects.<key>` to search a custom object you have no relationship to. See [Custom Objects in Liquid](/product-docs/liquid/overview.md#custom-objects).

When a **Field is changed** trigger fires on a custom object record, `trigger.type` is `custom_object_updated`. See [Custom Object Events](/product-docs/liquid/trigger-context-reference.md#custom-object-events).

***

## Deleting a custom object

A custom object can't be deleted until all of its records and every reference to it have been removed. See [Deleting a custom object](/product-docs/workspace-settings/objects/overview.md#deleting-a-custom-object).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.