Object Data Model

Audience: Developers and Solution Architects

Purpose: Explains how Objects are structured in Kizen, including how Records, fields, identifiers, and relationships behave across the platform.

Overview

Objects define the canonical data structures used across Kizen to store, relate, and operate on business data. They provide the schema layer that governs how Records are created, validated, related, and accessed.

This page defines the Objects data model, including Object definitions, Record instances, fields, identifiers, and relationship mechanics. It builds on concepts introduced in the Object Core Concepts.

How Objects Are Identified

Objects and Records in Kizen are identified using a combination of system-generated IDs and API-facing identifiers. Each plays a different role across the platform, including UI navigation, API operations, automations, and data imports.

System-Generated Identifiers

Kizen assigns immutable, system-generated IDs that uniquely identify data within a Business. These identifiers form the canonical identity layer of the platform.

Every Object and Record has the following system-generated identifiers:

• custom_object_id – schema-level identifier

• record_id – instance-level identifier

What Is A custom_object_id?

A custom_object_id uniquely identifies an Object definition within a Business.

What it identifies

• The Object’s schema

• Field definitions

• Relationship definitions

• Configuration type (Standard or Workflow)

What it’s used for

• Retrieving or describing Object schemas

• Determining which fields and relationships exist

• Applying validation rules to Records

• Driving configuration-dependent behavior in APIs and automations

Key characteristics

• Schema-level: it identifies the structure, not the data

• Stable: it does not change if the Object is renamed

What Is A record_id ?

A record_id uniquely identifies a single Record instance that belongs to an Object.

What it identifies

• One specific data Record (for example, a single policy, ticket, or claim)

• The stored field values for that Record

• References to related Records

What it’s used for

• Creating, retrieving, updating, or deleting Records

• Linking Records through relationships

• Displaying data in timelines, dashboards, and reports

• Triggering automations based on Record-level events

Key characteristics

• Instance-level: it identifies data, not structure

• Stable: it does not change if field values or display names change

Th platform needs stable, unambiguous references to both the schema (custom_object_id) and the specific data instance (record_id) in order to operate reliably across APIs, relationships, automations, and timelines.

API-Facing Identifiers

In addition to system-generated IDs, Kizen exposes API-facing identifiers. In API requests, Objects are referenced by API name.

These include:

• Object API names (for example, deals, policies)

• Field API names used in API payloads (for example, email, name)

API-facing identifiers:

• Are commonly used in API requests, automations, and imports

• Allow Records to be located without knowing internal IDs

• Resolve to system-generated identifiers internally

These API-facing identifiers resolve to system-generated IDs internally to ensure consistency and data integrity.

---

Object Lifecycle

The Object lifecycle governs how a Object’s schema is created, evolved, and eventually retired. This lifecycle affects how Records are validated and interpreted, but it does not directly manipulate stored data.

• Object created → schema defined: Creating an Object establishes a new schema, including its fields, relationships, configuration type (Standard or Workflow), and validation rules. At this stage, no Records exist, only the structure they will conform to.

• Schema modified → validation rules updated: Changes to an Object—such as adding fields, updating required rules, or modifying relationships—updates the schema that governs future Record writes. These changes affect how new or updated Records are validated but do not automatically alter existing stored values.

• Object deleted → schema removed: Deleting an Object permanently removes the Object schema and deletes all associated Records. This cannot be undone.

Schema changes apply uniformly across all Records for an object. Field types are immutable, and existing field values are not changed unless a Record is explicitly updated.

---

Data Structure

Every Object is composed of three core elements: fields, relationships, and Records. Together, these define both the structure of the data and how data behaves across the system.

Custom Fields

Custom Fields define the schema of an Object. They determine what data can be stored on Records and how that data is validated and used across the platform.

Fields specify:

• The type of data (text, number, date, select, relationship, etc.)

• Whether the data is required, read-only, or required only in specific contexts

• How the data participates in automation, reporting, integrations, and UI behavior

Custom Fields belong to the Object, not to individual Records. Objects exist primarily to support dynamic, business-defined schemas. Because every organization models data differently, the platform cannot predefine all possible fields. Custom fields allow each Object to evolve as business requirements change without requiring code changes.

Custom Fields and relationships define schema only. They do not store data themselves. For more information, see Custom Fields.

Records

Records are the actual instances of data created using an Object’s schema.

Each Record:

• Stores field values

• Represents a real-world entity (such as a policy, ticket, client, or claim)

• Can be related to other Records

While Objects define structure and fields define validation rules, Records contain the actual data. Record data is stored as a set of field values, where each value is associated with a specific field definition and validated against the Object’s schema at write time.

Schema changes affect how future writes are validated but do not retroactively modify existing stored values unless explicitly written. For more information, see Records.

Relationships

Relationships define how Records connect to one another across Objects. They are implemented as a specialized field type and always connect Record to Record, not Object to Object.

Relationships enable:

• Linking related business data (for example, a policy to a contact, or a claim to a policy)

• Cross-Object automation and updates, including between Records of the same Object

• Accurate reporting across connected Records

A relationship is defined at the Object level as a field, but its value is stored on individual Records as a reference to another Record. Relationship values are stored alongside other field values and follow the same validation and lifecycle rules.

When a relationship field is created, an inverse relationship field is automatically created on the related Object. Record-level updates to a relationship are reflected on both sides, enabling bi-directional navigation between related Records.

For more information, Object Relationships.

How These Pieces Work Together

Objects define schema. Custom Fields and relationships describe structure and rules. Records store values that conform to that schema, including references to other Records through relationship fields.

This separation between schema metadata and Record data allows Objects to evolve independently of stored values while supporting reliable validation, automation, and scalable integrations across the platform.

---

Object Configurations

All Objects share a common architectural foundation, but differ in behavior depending on how they are configured. Understanding the different Object configurations is critical when designing data models, automations, reporting, and integrations.

The platform supports the following configurations:

• Standard Configuration

• Workflow Configurations

Standard Configuration

Standard configurations are used to model structured data that does not move through a defined lifecycle and does not require stage-based or value-based tracking. They are best suited for reference or classification data rather than process-driven work.

Standard configurations:

• Include default system fields such as Name, Owner, and Date Created

• Support all custom field types and relationships

• Are fully accessible through automations and APIs

• Do not support stages, board (kanban) views, or pipeline dashboards

• Do not include system fields for value tracking or forecasting

Common use cases include assets, providers, advisors, facilities, locations, insurance plans, policies, and carriers. Use a standard configuration when you need structured records with consistent fields and relationships, but no lifecycle stages or pipeline-style reporting.

Workflow Configuration

Workflow configurations are used to model records that move through a defined lifecycle and require visibility into progress, status, and outcomes. They are designed for work in progress, transactions, or coordinated processes that evolve over time.

They use the same underlying mechanics often referred to as pipeline behavior. A configuration is considered a workflow when its primary purpose is to coordinate process execution rather than represent a static business asset.

Workflow configurations:

• Include all capabilities of Standard configurations, including custom fields, relationships, automations, and API access

• Support defined stages to represent lifecycle progression or process steps

• Support board views for visual management

• Enable stage-based automations

• Power dashboards, operational reporting, and analytics

• Support value tracking and percent chance to close when enabled

Workflow configurations also include additional system-managed fields such as:

• Stage

• Entity Value (optional)

• Estimated Close Date

• Actual Close Date (system-managed)

• Percent Chance to Close (optional)

• Reasons Lost (conditional)

Common use cases include lifecycle-driven or process-oriented Records such as deals, tickets, applications, renewals, onboarding flows, claims, projects, cases, implementations, escalations, compliance reviews, and service delivery.

Use a Workflow configuration when records move through defined stages, stage transitions drive automation, and visibility into progress or outcomes is required across teams or systems. A Workflow configuration can also be used as a sales pipeline by enabling Track Entity Value and Percent Chance to Close.

Architectural Implications

The choice between Standard and Workflow configuration has significant architectural consequences. It determines which system-managed fields exist on an Object, how Records participate in lifecycle-driven features, how automations execute, and whether data can be used in dashboards, forecasting, and stage-based reporting.

Workflow configurations include additional system-managed fields—such as Stage and Percent Chance to Close—that are intrinsic to the workflow model. These capabilities cannot be added to Standard configurations after the fact. Choosing the wrong configuration often requires recreating the Object to enable workflow-specific behavior.

Configuration choice also affects automation timing, event behavior, relationship design, and long-term scalability. Relationships introduced early in a data model can create dependencies across Objects that are difficult to reverse without significant refactoring.

API Implications

Standard and Workflow configurations use different endpoint families, expose different system-managed fields, and enforce different validation rules. Integrations must account for an Object’s configuration when constructing requests, handling responses, and designing automation workflows.

---

Schemas

Object Schema

The Object schema defines the structure and behavior of a Object in Kizen. It describes the schema-level configuration that governs how Records are created, validated, related, and accessed across the platform.

Record Schema

The Record schema represents an individual data instance that conforms to an Object’s schema. It contains the stored field values, system-managed metadata, and references to related Records.

For more information see, Records Data Model.

---

Additional Information

Supported APIs

Supported APIs

Objects support APIs for:

• Retrieving Object Field Options

• Retrieving Custom Object Details by ID

• Managing your Records

Object schema creation and modification are managed through the UI and are not performed via API.

Error States

Errors may occur due to:

• Missing required fields

• Invalid field values

• Permission restrictions

• Invalid or missing identifiers

Error responses follow standard API validation patterns

---

What’s Next

Next, explore Object APIs to see how this data model is used in real API requests and responses.

Related Topics

• Object Core Concepts

• Object Relationships

• Object Workflows

• Object Permissions

• Objects APIs