See related
No related articles

Data model overview

Last Update: Sep 2024 • Est. Read Time: 6 MIN
To check plan availability, see the pricing page.

The Kustomer platform is based upon an extensible data model that allows organizations to extend the application's functionality and store, manage, and interact with all relevant business objects. The Kustomer data model consists of two types of objects: standard objects and custom objects (KObjects).

In this article, we will discuss standard objects and custom objects (KObjects) in more depth, as well as the concept of custom attributes and the relationships between each type. For a brief introduction to the Kustomer platform, see the Kustomer platform overview. 

In this article:

Standard objects

Standard objects are the base set of objects installed in every organization, providing applications with an extendable customer-centric data model. 

The main list of standard objects installed for all organizations includes:

  • Customer
    The Kustomer data model is centered around the customer. The customer model represents a contact within an organization, including existing customers, prospects, leads, etc. 

    Customers can be uniquely identified in several ways:
    • By a unique identifier generated by Kustomer.
    • By an external ID supplied by the customer (this must be unique across all customers within an organization).
    • By a set of primary contact details including email address, phone number, or social profile id.

    For details about each attribute on the customer model including available search fields and template context variables, see our Customer API.

  • Company
    A customer can optionally be linked to a company. The company object is most relevant to B2B organizations, which might be more interested in managing a group of individuals than a B2C organization, which is most interested in talking directly to the end consumer. The company model has a one-to-many (1-M) relationship to the customer model. However, a company is not required on a customer model.

    For details about each attribute on the company model including available search fields and template context variables, see our Company API.

  • Conversation
    The Kustomer platform offers channel-specific applications to support various ways of interacting with customers. The conversation object is the standard object representing a set of customer interactions about a specific topic. 

    Conversations can span multiple channels and include messages and internal notes. The customer model has a one-to-many (1-M) relationship with the conversation model. A conversation cannot exist without an associated customer relationship.

    For details about each attribute on the conversation model including available search fields and template context variables, see our Conversation API.

  • Messages
    Along with conversations, messages also relate to channel application data within the Kustomer platform. The message object is the standard object that represents an individual interaction with a customer within a conversation. Each message has a direction (inbound or outbound) and a single channel (i.e. email, SMS, Tweet, etc.). 

    For details about each attribute on the message model including available search fields and template context variables, see our Message API.

  • Notes
    The Note model is an internal private message associated with a conversation. When creating a note, users can mention one or more internal users who will receive immediate notifications. 

    For details about each attribute on the note model, see our Notes API.

  • Events
    The event model is a standard model representing any event on a Standard Object, Custom Object (KObject), or application within the system. Events are supported for create, update, and delete actions. These events can be used to trigger a workflow to run custom business logic whenever a specific event occurs.

Click to enlarge

Custom objects (KObject)

Custom objects, referred to as KObjects, are objects that organizations can use to extend the application's base data model. As a result, organizations can store information specific to their business and link to customer records or any other standard or KObject. 

For example, if an organization wants to store orders placed by its customers on its website or mobile application, it can define an order Klass (defined below) and start ingesting order events using the API and inbound webhooks.

  • Klass
    Before you can create a KObject, an organization needs to define a set of attributes and relationships that make up an object. This is done through a class definition called a Klass. 

    A Klass includes a set of standard and custom attributes that together define all instances (KObjects) of a Klass. Klasses are uniquely identified by a Klass name that references KObjects and the Klass definition across the product. 

    All Klasses include a common set of attributes including:
    • externalId - identifier that uniquely identifies a specific KObject across a single Klass 
    • title - a short string title of the object
    • description - a long string description for the object
    • images - an array of image URLs
    • Rev - revision number used for optimistic locking purposes

Note: Klass data can be created, deleted, and retrieved using a set of APIs. For more details on KObject APIs, see our KObjects API.

Custom attributes

Custom attributes allow organizations to extend both Standard Objects and KObjects. Organizations can define new attributes on an object and provide additional metadata about the attribute, including a type, custom icon, color, and display name. 

These attributes are available across the system, including in search, reporting, templates, KViews, workflows, and more.

  • Types
    Each custom attribute is associated with a single type. Custom attributes support the following types:

    • Boolean (Bool) - A custom attribute of type boolean includes the following metadata: displayName, default, array flag, and multi flag.

    • Number (Num) - A custom attribute of type number includes the following metadata: displayName, default, min, max, array flag, multi flag, and enumeration.

    • Object (Obj) - A custom attribute of type object is a special type that provides one level of nesting for custom attributes. This allows organizations to create lightweight object relationships without having to create multiple Klass and relationship definitions. A custom attribute of type object can include the following metadata: displayName, array flag, and multi flag.

      For example, if you needed an order to have a set of items where each item had a title and color, you could do this in two ways:

      1. Using relationships with multiple Klasses - Create an Order and OrderItem Klass and a 1-M relationship between Order and OrderItem and custom attributes on orderitem for name and color. Additionally, you would need your Workflows and APIs to support creating and linking multiple KObjects together.

      2. Using Custom Attribute of type Object with a single Klass - Create an Order Klass with a custom attribute items of type Object where each item had a title and color attribute. Workflows and API usage would only need to be concerned with a single object.

    • String (Str) - A custom attribute of type string includes the following metadata: displayName, default, minLength, maxLength, array flag, multi flag, and enumeration. A string can have a maximum of 255 characters.

    • Tree - A tree is a special type of custom attribute used to represent a multi-level list of items. A custom attribute of type tree can include the following metadata at the root level: displayName and lastNodeRequired that is used to determine if the full path of a tree value needs to be selected on this property or if the value can be any subpath of the tree. Each node within a tree can define an id and displayname. 

    • Text- A custom attribute of type text includes the following metadata: displayName, default, minLength, maxLength, array flag, multi flag, and enumeration. A text string can have a maximum of 1024 characters.

      Note: A tree can be a maximum of 6 levels deep.


    • URL - A custom attribute of type url includes the following metadata: displayName, array flag, multi flag, and enumeration.

Custom relationships

A custom relationship defines the existence of a relationship between 2 object types in the system. A relationship between any Klass and a standard object of type company, customer, and conversation can be created. Custom relationships can have the following cardinality:

  • one-to-one (1-1)  - An example of a one-to-one relationship is a Customer to Birth Certificate. A customer will have only 1 birth certificate.

  • one-to-many (1-M)  - An example of a one-to-many relationship is a Customer relationship to Order. A customer may have multiple orders.

  • many-to-many (M-M)  - An example of a many-to-many relationship is with a Customer and a Product. A customer may own many products. A product may have been purchased by many customers. Multiple Klass / relationships must be created to define a many-to-many (M-M) relationship. For example, you can create a “Customer Product” Klass that has a one-to-many relationship with a Customer and a one-to-many relationship with a Product Klass.

Custom validations

Custom validations can be used to ensure the integrity of an object. For example, a specific custom field can be set before a conversation can be marked done. Validations can be defined on standard objects, including company, customer, conversation, message, and KObjects.

Note: Currently, custom validations can only be managed through the API.

FAQ

Q: Can I use KObjects to create orders in a customer’s timeline?

Yes, you can use the API or define a hook, trigger, and workflow to receive events from your order system and create / update orders within a customer timeline.

Q: Can I segment my customers with custom attributes and KObjects like orders?

Yes, all custom attributes on standard and custom objects are indexed by our search engine and exposed in our application for the purposes of segmentation. These searches can be saved and assigned to users / teams to drive proactive customer engagement and inbound support transactions.