Company Blog Support
Frank Hagan


    Back to Top

    Introduction to Custom Objects

    An Introduction by ONTRAPORT CEO Landon Ray

    In many businesses, you need to manage more than just "Contacts."

    Here's a quick example scenario: If you do B2B sales, you probably need to store "Companies" and maybe "Opportunities" in order to track which Contacts work for which Companies, and see and follow up with all the Opportunities for each Company and Contact.

    A contractor needs to be able to create ‘bids’ and follow up on each bid. You might find that one Contact requests several bids, and you’d want to see all of that Contact’s bids in one place.

    Custom Objects in ONTRAPORT allows you to create and store these new kinds of data sets to match the way your business really works. What’s really amazing is that ONTRAPORT allows you to use the tools you’re already familiar with -- Forms, Sequences, Rules, Messages, etc. -- to create automated systems to manage these new object records.

    Let’s use that contractor as an example. He probably does kitchen remodels, bathroom remodels, new decks, and more. Since he’s so good at what he does, he more than likely works repeatedly with the same clients.

    For each job, he’ll want to create a new Bid. Each Bid includes a lot of information on the project such as project type, estimated total cost, estimated labor and materials costs, estimated time to complete the project, proposed start date, and more.

    To log this data and connect it to the client, our contractor creates a new object in ONTRAPORT called "Bids." Just like Contacts, this new object has its own Field Editor so he can create all those custom fields. He can do this when he’s creating the object or do it later.

    Then in order to keep track of which Contact each Bid is created for, he creates a Relationship between this new object, "Bids," and the existing object "Contacts." (Learn more about the three types of Relationships below.)

    Once this is all set up (a process that takes mere minutes in the new Object creation wizard), the contractor's system will look like this:


    And when he opens an individual Bid, it’ll look like this:


    Finally, when he looks at a Contact, the Bids will show up like this:


    This is a great start. Now we’ve got a slick way of storing all the information about each Bid for each Contact in ONTRAPORT.

    But here’s where things get tricky!

    As you can see in the navigation screenshot above, the new Bids object comes complete with its own Sequences, Rules and Messages. For this reason, you're able to subscribe the Bid itself to a follow-up Sequence!

    Imagine being able to automatically send out an email with your proposal, then follow up a few days later with a phone call to check in on the client. Then, once the Bid is accepted, a new Sequence might kick off, thanking the client for their business, and letting them know what to expect. Maybe a day before the start date, another email or SMS goes out to the client, reminding them that the construction crew is going to show up the next morning. You get the idea …

    As you can see, the ability to create Custom Objects and then run automated Sequences for them provides virtually unlimited possibilities for streamlining and automating more complex business processes.

    The rest of this article will give you a deeper look at Custom Objects.

    Custom Objects' Features

    Several new features are added to ONTRAPORT with Custom Objects:

    • Custom Objects Activation: Turn on Custom Objects in Administration > Advanced Features > Custom Objects
    • Custom Objects Creator:  Administration > Data > Custom Objects is used to create and edit Custom Objects.

    • Navigation Manager: Within Administration > Data > Custom Objects you can specify if a Custom Object is displayed in your primary navigation menu, the icon it uses, and the color of the listing. Click the name of the Custom Object to enter it, then Settings in the left menu.

    • To: Fields for Messages: In each Message editor the drop down dialog boxes will include the email fields for the related custom object records. This permits you to send messages to the related Object: for example, sending an email to the employees of a company from the Company object.

    • To: Fields in Sequence Email Steps: You can choose the email field for related custom object records in Step and Date Sequence Email steps. 

    • Changes to Form Builder: You are now able to add fields from more than one object on a single Smart Form, allowing creation or updates of records in multiple objects.

    • Object Selector in Dashboards (coming soon!): You will be able to select the Object you want to report on in Dashboard Metrics.

    • Related Object Data Fields: This is a new type of field --not the traditional text or numeric field -- that you’ll find in each Field Editor. This "view-only" field allows you to expose the data in any field of the related object record. It is not used as a trigger for Rules, but allows you to view the data in the Object Record. It also appears in the first level of drop down selection boxes for merge fields and column headings.

    • API:  Each new object has its own API endpoints.

    • Notes: Each object has notes under the Task manager tab. Notes from one object can not be seen placed into another object. [newest note] merge fields can be used for task/email notifications, fulfillment lists and are exportable by object.
    • Automation Log: Actively records and stores a list of any manual or automated actions performed on your custom objects records. This feature comes in handy when you need to trace the path of your object records through your automated builds for troubleshooting, or want to test any new builds you're likely to implement.  The actions can be performed by Users, ONTRAPORT Smart Forms, Campaigns, API, Rules (advanced feature) and in-Sequence Rules (legacy feature). The Automation Log is located in the Object Record on the History tab.


    Understanding Relationships

    Custom Objects are easy to create and manage once you understand how the relationships between Objects work.


    Custom Objects can be related to the Contacts' Object or to any other Custom Object in one of three ways:

    • One-to-many

    • Many-to-many

    • One-to-one

    One-to-many Relationships

    In one-to-many relationships (sometimes called Parent-Child relationships) a record in one Object (the Parent Object) can be related to any number of records in the other Object (the Child), but the Child object can have only one parent object. This is the most common type of Object you'll create.


    Example: In the contractor example from the introduction, the Bid Object is the "Child" Object and Contacts are the "Parent" Object. Each Contact can have many Bids associated with them (e.g., one for remodeling their kitchen, bathroom and deck), but a Bid will only have one related Contact as the parent.


    Another common one-to-many example involves a Company's or Account's Custom Object, where the name, address and other company information of a Contact’s employer is stored. In a one-to-many relationship to another Object, such as Contacts, the Company record can have many related Contacts (all their employees), but each of those Contacts can only have one Company. The company is the Parent (the "one" side of the relationship) with many Contacts as employees (the "many" side of the relationship).


    When you create a one-to-many relationship, the related fields in each field look like this:


    On the left, the Contacts are listed in the Company Object record. In this case the Company Object record is for a business named "SendPepper;" it is the "One" side of the one-to-many relationship, or what we call the "Parent." Three Contacts are related to this Company on the right-hand side, so we know these Contacts are on the "many" or the "Child" side of the relationship. On the right, we see "Alan Turing's" Contact Record. We have named the relationship field "Business" when it appears in the Contact Record (more on this later). We can see this Contact's related "Parent" Object is the company named "SendPepper".


    Many-to-many Relationships

    Many-to-many relationships allow each Record in either Object to have connections to many Records in the other Object. For example, in a school, the Teachers Object and the Students Object would have a many-to-many relationship. Each Teacher can have many Students and each Student can have many Teachers.


    When you create a many-to-many relationship, the related fields look in each Record look like this:


    On the left, a Student record can have many teachers and, likewise, a Teacher Record on the right can have many students.


    Note: Because of the complexity of many-to-many relationships, certain features are not available when this Object type is selected. For example, you won’t be able to send emails to a Related Object’s email in a many-to-many relationship. That feature is only possible with one-to-one relationships or one-to-many relationships. The same is true for Rules that are triggered by changes to related Objects.


    One-to-one Relationships

    A one-to-one relationship means one Record in the new Object can be linked to only one record in the other Object. One-to-one relationships are useful in certain circumstances, but will probably be your least used relationship type. In many cases, you can simply add a custom field to the original record to avoid having to create a new database Object.


    A common request is the ability to list a spouse and tying the spouses to each other. Creating a separate Custom Object and adding fields to it would seem to make sense. But ONTRAPORT includes a very powerful feature: You can relate any Object to itself where all the fields, etc. are pre-formatted for you. There is no need for a "spouse" Custom Object as you can simply relate the Contacts Object to itself in a one-to-one relationship. Call the relationship "Spouse" and you can select any other Contact to be the spouse.  Show me



    Of course, you can create a Custom Object and relate it to another object in a one-to-one relationship.


    Creating a Custom Object

    Creating a One-to-Many Relationship

    In this example we'll create a one-to-many Custom Object for business records named "Company". It will be the parent, or the Object on the "one" side of the one-to-many relationship, with the Contacts database the child, or "many" side of the relationship.


    First, click your account's email address at the top right and select Administration > Data and then Custom Objects. Click the New Object button and we'll get started using the simple four step process to create a new Custom Object.

    1. Name the new Custom Object. Fill in the singular form of the Custom Object's name; ONTRAPORT will make the best guess as to the plural, possessive and plural possessive forms of the name. Edit them as necessary. In this example, we are using "Company". When satisfied, go to Step Two by clicking the Next button at the top right. Show me


    2. In Step Two, the Add Fields screen appears. Note the existing tabs and fields: Show me



      • The Company Information tab is shown. The Sequences and Tags section is displayed at the top.

      • The System Information tab has the unique Company ID number, Date Modified, Owner, Last Activity date and Date Added fields. These system-added fields mirror those in the Contact Records with which you are already familiar.

      • The Company History tab contains the Company Object's history log, named "Company Log". The log will contain the tracked activity for the Company such as page visits, form fill-outs, etc.

      • The Task Manager tab will contain any Tasks created for the company.

      Let's add a custom section and some custom fields for the company records:

      1. On the Company Information tab click the + New Section link and add a new section named Company Information. Show me


      2. Click the + Add Field link and add a text field named "Company Name".

      3. Continue to add fields as desired. You have the full range of field types available:

        • Checkbox

        • List Selection

        • Long Text

        • Numeric

        • Price

        • Phone

        • State

        • Dropdown

        • Text

        • Email

        • SMS

        • Address

        • Related Object Data


        When satisfied with the added sections and fields, click the Next button at the top right to go to Step Three.

    3. Click the + New Relationship link and select an Object to relate this new object to; in this example, we are choosing Contacts. Choose the following in the dialog box that pops up:

      1. Relationship Type: One-to-many

      2. The Company is: Parent

      3. Where should we put the other object in the Company's record: Company Information.

      4. Where should we put the Company in the other object's record: Contact Information

      5. What should we call this relationship in the Company record: Employees

      6. What should we call this relationship in the Contact record: Company  Show me


      7. Click Save. The screen refreshes to allow you to create relationships with other Custom Objects if desired. Click Next in the upper right.

    4. The Settings page appears. Set how the Custom Object record is identified in other Custom Objects. For our Company Object, we will use "[Company Name], [Company City]". Show me


      Consider how you would use this to show other information in a different kind of related Object. For our contractor’s Bid Object, using merge fields such as "[Bid Name]:[Bid Type], [Bid Estimate]" provides "Locke Kitchen:Kitchen Remodel, $32,768" in the drop down and section headings. That’s more descriptive than simply the Bid Name and provides essential information about the Bid at a glance.

      Consider configuring these optional settings:


      Click the Company's name in the navigation menu to edit the icon and change the color theme in the menu. Click and drag the up/down arrows on the left to reposition the Custom Object in the navigation menu.  Show me




      Click Finish when done.


    From the Custom Objects screen you can click on the name of any Custom Object to edit the name, manage the relationships, and adjust the settings just completed, including adding fields and sections, etc.


    You can return to the Contacts database and open a contact for editing by clicking on the name. A drop down box for Company will now be present in the information section showing the records in the Company's Custom Object. Don't worry -- you can also add a new company to that Custom Object from within this Contact Record if desired.



    Creating a Many-to-many Relationship

    Now that we've seen how easy it is to create and configure a new Custom Object, let's look at creating a many-to-many relationship. Step One, where you name the Custom Object, and step Two, where you specify the new Custom Object's data fields are identical to the above section (Creating a One-to-many Relationship). In Step Three, it begins to differ.


    Following the method in Step One above, create a new Custom Object and name it "Teachers." Following Step Two above, create the new section "Teacher Information" and the fields shown in the image below. Make the email field "unique" and "required" by clicking the check boxes:  Show me




    Unique fields automatically become index fields for your new Custom Object. Any time data comes in from a Form fill-out, etc., that includes the unique field, that information is used to update data if a Record already exists; otherwise it will create a new Record.


    Now, let's pick up in Step Three and define the relationship:

    1. Teacher is related to: Contacts

    2. Relationship Type: Many-to-many

    3. Where should we put the other object in the Teacher's Record?: Teacher Information

    4. Where should we put the Teacher in the other Object's Record?: Contact Information

    5. What should we call this relationship in the Teacher Record?: Student (Singular) and Students (plural)

      Note that we can call the Contact Records "Students" in Step Three without affecting the Contact record itself. This is handy if you have more than one relationship to the same object. We could also establish another relationship for "Parent" Contact Records in the same way, and both "Students" and "Parents" would be entries in the same Contacts database.

    6. What should we call this relationship in the Contact record?: Teacher (singluar) and Teachers (plural)  Show me


    Step Four is also the same as above in the One-to-many directions. Configure the way you want the Teachers Object to be displayed elsewhere, such as using the merge fields "[Teacher Name], [Teacher Email]", then set the icon, color theme, and position on the navigation menu.


    In any Contact Record, you can select one or more Teachers or, conversely, select one or more "Students" (contacts) from within any Teacher record. You can also "Create New" Teachers or Students (Contacts) from the related Object. Show me




    Creating a One-to-one Relationship

    While creating an entirely separate data Object for a one-to-one relationship is rare, it's sometimes easier than adding custom fields. In this example, our fictional company sells serialized software packages that are frequently re-assigned to different sales people. Because we need to track not only the serial number but the purchase date and support term, having the data in another Object will be easier than manually deleting the data from one Contact Record and manually adding it to another.


    Create a new Custom Object and name it Software in Step One. In Step Two, create the fields for the software, including the package name, SKU, serial number, purchase date and support term in years. Make the serial number unique.  Show me



    In Step Three, configure the relationship details:

    1. Software is related to: Contacts

    2. Relationship Type:  One-to-one

    3. Where should we put the other Object in the Software's record? Software Information

    4. Where should we put the Software in the other Object's record? Contact Information

    5. What should we call this relationship in the Software record? User

    6. What should we call this relationship in the Contact record? Software Serial


    In Step Four, configure how you want the Software Object to be displayed, using the merge fields "[Software SKU], [Software Serial Number]", then set the icon, color theme and position on the navigation menu.


    The Contact Record will now have a drop down selection box in which you can select the one Software Serial Number you'll assign to that Contact. Re-assigning a Software Serial Number is as easy as selecting the serial number in the new Contact Record. It will automatically be removed from the prior Contact when selected. Show me



    Adding Records to Your Custom Object

    ONTRAPORT makes it easy to add new Records to any Custom Object. You can:

    • Add the new Record manually in the Object Collection.

    • Add a new Record from a related Object.

    • Create a Smart Form so Records can be added from any web page.

    • Upload a CSV file with new Records in it.

    • Use the API to create new Records.


    Manually Adding Records

    Click the Custom Object in the navigation menu and click the New button: Show me



    You can also manually add Object Records from a related Object. In this example, we can add a new Business from a Contact Record: Show me



    Adding Records Using Smart Forms

    Each Object includes its own Smart Forms, making it easy to add Records. Create the Smart Forms using the same process you have always used in ONTRAPORT. (To learn more, check out our Smart Form Builder Overview article.) For Custom Objects, ONTRAPORT has added expanded capabilities to the Smart Form builder.


    Fields from some related Objects are available using the Smart Form builder Add Field button. This allows you to create multiple Object Records with a single form. Related Object fields are accessed by clicking the right arrow next to the other Object's name:  Show me



    Object fields are available subject to the following rules:

    • One-to-one relationship: All fields from both Objects are available.

    • One-to-many relationship: The Parent Object's fields are available in the Child Object's Smart Forms, but not the reverse (the Parent Object cannot access the Child Object's fields).

    • Many-to-many relationship: No fields from the other Object are available.


    Fields from other Objects do not appear if the current Object is the Parent Object in a one-to-many relationship, or if the relationship between the Objects is a many-to-many relationship.

    Upload Records Using a CSV File

    If you’d like to mass import Records into your new Object, you can use the same process you use to Import Contacts. Be sure to prepare a standard Comma Separated Values (CSV) file for the import. The CSV format is often available as an export option from other programs, and other file types can be converted using programs such as Microsoft Excel or LibreOffice.


    Follow the instructions in the Import Contacts article to format your file for import. If you are located in the EU or northern Africa, Excel may force a semi-colon separator instead of commas; see the information in the above article under the headline "Converting Semicolon Separated Fields (EU Format)" for formatting instructions.


    To import your CSV file, click the Object Collection, then Settings and the Import link: Show me


    Creating Records With the API

    The documentation to create, update and delete Object records using ONTRAPORT’s Application Programming Interface (API)can be found here. This functionality is advanced and should be used by experienced developers or programmers. ONTRAPORT does not provide support that teaches how to use the API.



    Merging Records in Your Custom Object

    Custom Objects records can be merged using the familiar Merge Duplicate Contacts interface. In the Custom Object collection, select Settings and then Merge Duplicates (Contacts screen shown in this example). 

    merge duplicates

    The Merge Duplicates process allows you to select the fields to search for a duplicate, and then presents each duplicate record for you to merge. It is an intuitive process but you can refer to the instructions in our Merge Duplicate Contacts article for more information.


    Understanding Rules and Related Custom Objects

    Rules in One-to-many Related Objects

    • Rules in the Parent Object:

      • Cannot be triggered or act upon a Child Record or the Child Record's fields.

      • Cannot trigger emails, tasks, etc. in the Child Object.

      • Cannot take any action upon a change in a Child Record (e.g., a Child Record is added or removed from the Parent Object).

      • Cannot take any action based upon a change in a Child Record's fields, such as an email address change, address change, etc.

    • Rules in the Child Object:

      • Can be triggered by a change of the linked Parent Record but CANNOT be triggered by a change in any of the linked Parent Record's fields.

    Rules in Many-to-many Related Objects

    Rules cannot be triggered by an event or action in another Object in a many-to-many relationship.


    Rules in One-to-one Related Objects

    Rules can be triggered by a change of the linked Record but CANNOT be triggered by a change in any of the linked Record's fields.


    These restrictions are due to the nature of the database Objects, and may seem limiting at first. Custom Objects expose the fields of the related objects in Messages, Tasks and Forms. You can still automate notifications, etc. without the use of cross-object Rule activity, as shown in our use cases below.



    Use Cases


    Track Serial Numbers (One-to-many)

    This use case presents a common data configuration, a one-to-many relationship between two Objects that enables automated notification when a field changes in the Parent. Remember the Parent is the "one" side of the one-to-many relationship.


    In this use case, we sell multi-user software. The remote employees of a business that buys our software use the serial number to activate their copy of the software. Previously, custom fields were used to store the company name, details and the software serial number in every Contact Record. Updates were difficult because the company name was not always entered into the custom fields correctly, so Rules, Contact Groups, etc. did not always include all the employee records.


    Using Custom Objects, we create this automated system:

    1. A Custom Object named "Businesses" is created. In addition to the usual company information fields such as address and phone numbers, a text field named "Serial Number" is added.

    2. The Businesses' Custom Object is related to the Contacts database, where the employees of the company are stored. The relationship is "one-to-many" with the Business as the parent object. The Business can have many employee Contacts, but each Contact only has one Business as an employer. The Contacts are called "Employees" in the Businesses records.  Show me


    3. The Businesses Custom Object has the companies and serial numbers added via a CSV import.  Show me


    4. Each of the Contacts are associated with their company by selecting the company in the Contact Record.  Show me


    5. Our goal is to automate notifications of a serial number change that happens each time the company renews their software license. We create the notification email first.

      1. In the Businesses Custom Object, we create a new message.

      2. The parent object can send email to related records in a Child Object. The "Send email to" drop down allows us to select the Employees, then select the email field for the Employees.  Show me



      3. The merge fields in the email editor expose the Child Object's information. We can drill down to find the employee's first name. We complete the email using merge fields for the serial number (stored in the parent object) and the employee's first name.  Show me



      4. Save the notification email.

    6. Create a Step Seqeunce in the Businesses Object and add the email just created as the first step. Set it to "Send Immediately." Because the serial number can change frequently, select the option in Settings to "Unsubscribe contact after last step". Save the Step Sequence.  Show me


    7. Create a Rule that adds a Business to the Step Sequence above when the software's serial number changes.  Show me


    8. How this works:

      1. When the serial number field in the Businesses record changes, the Rule adds the Company to the Step Sequence.

      2. The Step Sequence sends an email to all the related Contact Records (i.e., the employees).

      3. After the email is sent, the Step Sequence unsubscribes the Businesses record from the sequence. The process will start over next year when the serial number is renewed again.

    If you prefer to manually broadcast your email, select the Child Object Records in the Parent Object Record and perform Group Actions, such as sending emails, on them.  Show me




    Teachers and Students (Many-to-many)

    Many-to-many relationships are uncommon and, due to the way the objects interrelate, the options available for automation are limited. The Custom Objects cannot act on or effect changes in the related Object.

    • Each Object will list the Records in the other Object.  Show me

    • You cannot trigger an action based on an event in the related Object Records.

    • Unlike a one-to-many relationship, you cannot send email to a related Object Record.



    Spouses (One-to-one)

    An Object can be related to itself. Linking two spouses together in a one-to-one relationship in the Contacts database is a common example. Here are the steps to do so:

    1. Click your email address in the top right and select Administration from the drop down.

    2. Click on the Custom Objects link to open the Objects page.

    3. Click on the Contacts Object to open it for setting relationships.

    4. Click Manage Relationships.

    5. Click the + New Relationship link. Relate the Contact to "Contacts" and set the Relationship Type to "One-to-one." Then add the other Object to the "Contact Information" section in the Contact's Record and call the relationship "Spouse".  Show me

    6. Within a Contact Record you can choose a Spouse.  Show me



    Search results will show both the Contact Record and the spouse's Contact Record.  Show me



    You can send an email to the Spouse Record in a Rule or Sequence. In this example, we send a birthday reminder email to the contact's Spouse in a Date Sequence

    1. Create a Date Sequence with an email step triggered by the birthday  Show me

    2. Send the email to the Spouse >> Email address. Use the [Spouse//First Name] merge field for the salutation and include the regular [First Name and [Birthday abb+0] merge fields for the reminder information. Remember, the spouse Record having the birthday is the one who triggers the reminder email!  Show me

    3. Subscribe your Contacts to the Date Sequence. Their spouses will be sent the reminder email according to the schedule set in the email step.



    Children (One-to-many)

    An object can relate to itself in a one-to-many relationship as well. In this example we will be using the Contacts database and creating a relationship for "many" children of a single "parent" Contact Record.

    1. Navigate to the Custom Objects screen by clicking on your email address at the top right, selecting Administration and then the Custom Objects link.

    2. Open the Contacts tab. Click the Manage Relationships link, then the + New Relationship link. Set the Contact as related to "Contacts" and relationship type "One-to-many." Then put the information into the "Contact Information" section. Call the relationship in this Contact Record "Children" and in the other Contact, call the relationship "Parent".  Show me

    3. You can connect the child to the parent Record by choosing the parent in the Contact Record  Show me


    The children will be listed in the Parent Contact Record; Group Actions can be performed on them from there.  Show me



    For instance, you can send an email to the Parent Record in a Rule or Sequence. This example sends a birthday reminder triggered by the Child Record's birthdate in a Date Sequence.

    1. Create a Date Sequence with an email step triggered by a birthday.  Show me

    2. Create the email to send to the parent of the child. Set the "Send email to" field to Parent >> Email. Remember to use the drill down "Parent" merge fields for the saluation, etc.  Show me

    3. Subscribe your Child Contacts to the Date Sequence. The parents will receive the email reminder message according the schedule set in the email step.


    Articles in this section

    Created - Updated
    Have more questions? Submit a request


    • Avatar
      Christopher O'Keefe

      This is powerful stuff - move over SalesForce!!!

    • Avatar
      Vincent Foo

      Hi Frank,


      We have create a few different objects in Ontraport (Gardians, Enquiries and Parents).  We tried building a lead gen system but somehow we are not getting the expecting outcome. 


      Scenarios: Create a Landing page with an embedded Smart Form to collect leads and send an email with a downloadble pdf.  We tested this and somehow the email doesn’t fire and submission goes into Guardian but not enquiries which we could like them to be.


      Thank you!

    • Avatar
      Frank Hagan

      Hi Vincent - I would direct your specific question to our Support team at

    Powered by Zendesk