The developer’s guide to custom objects 

Data-driven, personalized messaging: it’s the cornerstone of a marketing strategy that drives engagement, conversions, and long-term value. You’re already personalizing your messages with your customer data, right? (If not, get started already!) But if you’re not leveraging your business data too, you’re leaving a lot on the table.

If you want to tap into all your data, it’s time to unleash the power of custom objects. With custom objects, you can bring your many-to-many data model into Customer.io Journeys to drive personalization and segmentation in your messaging. That’s because custom objects take you beyond customer data by building relationships between people in your audience and aspects of your business.

The sky’s the limit with custom objects: you can bring in any business data that matters to you. Endless options can be overwhelming, so to help you decide what business data to use—and how you structure it in Journeys—we recommend starting with the data used for your company’s marketing and messaging campaigns.

Read on to learn how to implement custom objects in Journeys, then get step-by-step instructions for five use cases you can incorporate into your campaigns.

To get started with custom objects in Customer.io Journeys, you can choose to import existing object data or create them from scratch within our platform.

Importing your objects data into Journeys is a great way to leverage it quickly and efficiently. There are a few ways you can do this:

• Direct integrations with Data Pipelines: Use our native CDP to connect your source data directly with Customer.io. This option supports most integration methods, making it easy to import and sync data from various sources, including Salesforce.
• CSV upload: For a quick and straightforward option, you can upload a CSV file of your objects directly into Customer.io. This method is useful for smaller datasets or one-time imports.
• Reverse ETL: Sync object data from your databases or data warehouses to use it directly in Customer.io for precise segmentation and personalization.
• Third-party CDPs: If you already use a CDP, connect it to Customer.io to import your object data seamlessly.

If you’re starting fresh or want to experiment with custom objects directly within Customer.io, you can create them yourself within our platform. This approach allows you to define object types, populate them with specific data, and set relationships with people profiles, giving you complete control over the structure and details of your data setup.

Think of the object type as an umbrella category (like accounts, appointments, events, or courses) and an object as an individual aspect of your business within that category (such as specific accounts, types of appointments, individual events, etc). Every object type can have many objects (hundreds or even thousands) categorized within it.

How to create an object type:

• Head to the side menu of your Customer.io workspace and select Custom Objects.
• From there, click Create Custom Object; choose an object type from the list or make your own.
• Give your object type a Name and choose Singular for the form.
• Journeys will automatically generate a unique object_type_id that you’ll use when passing us your object's data.

Next, it’s time to make the magic happen: create relationships between objects and people. This is how you’ll segment people and personalize messages using your object data.

How to set relationships between objects and people:

• Go to the top-right dropdown menu from the People page and select Add Relationships.
• Select each person you want to relate to the object.
• Choose the object type, then select each object you want to relate to the people you selected.

These instructions cover implementing custom objects using the Journeys UI—but that’s not your only option. Once you get the hang of custom objects, you’ll devise more ways to harness your business data. You can use a variety of methods to create and update your objects including CSV, CRMs like Salesforce and Hubspot, data warehouses, and even Google Sheets.

Now, you’re all set to leverage custom objects for data-driven personalization in your campaigns!

• You can trigger campaigns based on changes to custom objects (i.e., when an account’s name is updated) or relationships (i.e. when a person becomes associated with an account).
• You can create segments based on people’s relationships to custom objects (i.e. a segment of all people related to an account).
• You can use objects in Liquid to trigger campaigns and personalize message content.

Now that you know the nuts and bolts of custom objects, let’s put it into practice with five use cases that are especially effective for product-led companies.

Collaboo is a subscription-based team collaboration platform. Every company has employees, some members of multiple teams, who utilize the service. Each employee is either an admin or an individual contributor (or both!), depending on the team. Collaboo wants to provide ultra-relevant onboarding for people's different roles in their product.

• Create an object type: Name the object type Companies. This will be the umbrella for all the specific companies using Collaboo.
• Create objects with attributes: Three companies have just signed up for Collaboo: Acme X, Acme Y, and Acme Z, so Collaboo creates three objects (one for each company).
• Relate objects to people: Now, Collaboo selects the people who work at each company and associates them with the relevant object: employees of Acme X are associated with the Acme X object, and so on.
• Set relationship attributes: Collaboo creates a relationship between each person and the custom object with the attribute user_role. This describes how each person is related to each company (i.e., whether they’re an admin or an individual contributor).
• Trigger onboarding campaigns: Collaboo has built separate onboarding campaigns for admins and contributors. So, they construct two segments—one for each user role—and trigger the appropriate campaign whenever a new person joins their audience.

TradeUp is an online investment management service. They want to build loyalty among their biggest business customers by offering white-glove customer support, so they assign each one a dedicated account manager.

• Create an object type: Name the object type Accounts—this will be the umbrella category for every business that has an account with TradeUp.
• Create objects: TradeUp creates an object for each customer account they manage: Account A, Account B, Account C, and so forth. Each object is given two attributes: account_type and portfolio_amount.
• Relate objects to people: Now TradeUp associates each person in their list with the appropriate Account object.
• Trigger a campaign: TradeUp builds a campaign that assigns a dedicated portfolio manager to each person whose portfolio is over $10k and adds them to a monthly investment advice email tailored for their VIP customers.

TeleWell provides virtual mental health counseling (including therapy and medication management) through a secure online platform. They need to make sure patients show up for appointments—and streamline appointment management for their doctors at the same time.

• Create an object type: TeleWell names the object type Appointments—this will be the umbrella category for all types of appointments.
• Create objects with attributes: TeleWell creates the appointment object and the attributes appointment_type (for therapy or medication management) and appointment_status.
• Relate objects to people: TeleWell relates every patient in their audience to the appointment object and uses the attributes to differentiate between types of care.
• Set relationship attributes: TeleWell outlines a relationship between each person and the custom object with the attribute user_role. This describes how each person is related to each appointment (i.e., whether they’re a patient or a doctor).
• Trigger patient campaigns: Whenever a patient schedules an appointment, TeleWell triggers an appointment reminder message, personalized with the date, time, and name of the doctor—plus a link to a pre-check-in survey.
• Trigger doctor campaigns: Doctors automatically get a personalized message whenever one of their patients books or cancels an appointment. TeleWell also messages a doctor when a patient completes their pre-check-in survey so the provider has all the necessary information.

Dweller is an online marketplace for house sale listings. One of their key marketing initiatives? City tours in hot real estate markets. The next event is in Madison, WI, and Dweller needs to invite only those interested in joining that city's tour.

• Create an object type: Dweller names the object type Events—this will serve as the category for every specific event.
• Create objects with attributes: Next, Dweller creates an object for the upcoming Madison tour, naming it Madison WI and giving it an event_interest attribute.
• Relate objects to people: Now it's time to relate people to the Madison WI object: customers who have added the event to their favorites or signed up to get notifications about it.
• Trigger a campaign: Dweller builds a segment and triggers an event announcement in-app message to all the customers related to the Madison WI object. Because they know that highly personalized messages get the best engagement, they leverage first-party data to include a photo of a home listing in Madison that each individual has viewed on their platform.

CodeCamp provides live online courses for developers in a variety of programming languages. Once a student signs up for a class, CodeCamp ensures their experience is personalized and engaging. First, by stopping marketing messages that are no longer relevant, and second, by sending messages to get them ready for their first class.

• Create an object type: CodeCamp names the object type Courses—this is a category for every course CodeCamp offers.
• Create objects with attributes: Next, CodeCamp creates an object called Python 101, including an enrollement_status attribute.
• Relate objects to people: CodeCamp will use filters to move people in and out of campaigns based on their enrollment status, associating everyone in their audience with the Python 101 object.
• Trigger one campaign and stop another: Using conditional logic, CodeCamp targets students with different messages based on their enrollment status for a particular course. As soon as someone enrolls in Python 101, they’ll stop receiving promotions for it, and instead get a message containing all the course materials and instructions for joining the online class sessions. CodeCamp can also follow up with additional messages to keep students engaged as they await the first day of class! And anyone who hasn’t taken Python 101 will still be sent marketing messages for the class.

These use cases should give you a solid baseline for exploring custom objects. And once you create a couple, you’ll probably come up with all kinds of ideas for bringing your business data into your campaigns. The beauty of custom objects is that they allow you to extend your messaging's data model beyond people and into the rest of your business.

Ready to give it a try? Choose the next step in your custom objects adventure:

• Learn more details about the how and why behind custom objects
• Read the full documentation and start creating your first object now