Skip to main content
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
Custom objects are not enabled for every workspace. If you don’t see the Custom objects section on the Objects settings page, contact Conversion.

​
Key concepts

​
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.
  • 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. 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

  • Custom objects enabled for your workspace
  • 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 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. Salesforce-synced objects get their fields automatically.
  3. Create 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.
Onboarding with Conversion? Let your Deployment Strategist know when this is done and we’ll check it on our end.

​
Getting records into Conversion

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.

​
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.
  • 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. 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.
  • 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

Filters can check related records in audiences, workflow conditions, records list views, and lead scoring 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: For the full filter reference, see Unified Query Engine.

​
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: 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 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:
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. When a Field is changed trigger fires on a custom object record, trigger.type is custom_object_updated. See 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.