> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/concepts/objects/records/records-data-model.md).
# Records Data Model
{% hint style="success" %}
**Audience:** Developers, Solution Architects, Technical Integrators
**Purpose:** Explains how the space.vars.entities Data Model structures, identifies, relates, and governs operational business data across the platform.
{% endhint %}
## Overview
The space.vars.entities define how operational business data is structured, identified, related, and governed across the platform.
This page defines the architectural components of space.vars.entity management, including identifiers, field values, relationships, associations, and governing constraints. It builds on concepts introduced in [Records Core Concepts](/docs/concepts/objects/records/records-core-concepts.md)**.**
### How Records Are Identified
Every space.vars.entity must have a unique identifier within its space.vars.object. This ensures space.vars.entities can be reliably retrieved, updated, and referenced across workflows, reporting, and integrations.
#### Primary Identifiers
For most space.vars.objects, the **Record Name** serves as the primary identifier for each space.vars.entity. It must be unique within the space.vars.object and is used in lookup, upsert, and integration scenarios.
For Contact space.vars.entities, the primary identifier is **email**. Because space.vars.contacts are communication-oriented, email functions as both a contact and a unique identity key, while still operating within the same space.vars.entity model.
#### API-Facing Identifiers
While space.vars.entity names and email addresses function as primary business identifiers, the API uses system-generated identifiers for space.vars.entity-level operations.
* **Record ID:** System-generated at space.vars.entity creation, immutable, and globally unique. Used for retrieve, update, and archive operations, and serves as the authoritative identifier in API interactions.
* **Object Identifier:** space.vars.entities are scoped within an space.vars.object and may be referenced using either the space.vars.object API name or the space.vars.object ID when performing API operations.
* **Lookup and Upsert Identifiers:** space.vars.entity Name is used for most space.vars.object space.vars.entities, and email is used for Contact space.vars.entities. These operations rely on space.vars.object-level uniqueness constraints and are subject to conflict-handling rules.
* **Field Identifiers:** API responses reference fields by field ID or field API name. Integrations should rely on stable identifiers rather than assume fixed field structures.
***
## Record Lifecycle
The space.vars.entity lifecycle governs how stored business data is created, modified, archived, and restored. Unlike space.vars.object lifecycle changes, space.vars.entity lifecycle events operate directly on stored data.
* **Record created → data instance established:** Creating a space.vars.entity stores a new instance of structured data within an space.vars.object. At this stage, the space.vars.entity receives a system-generated UUID and becomes subject to schema validation, permissions, and lifecycle tracking.
* **Record updated → values modified:** Updating a space.vars.entity modifies stored field values in accordance with schema validation rules. Changes generate timeline activity and update system-managed attributes such as modified timestamps.
* **Record archived → removed from active operations:** Archiving a space.vars.entity removes it from active operational views while preserving stored data and historical activity. The space.vars.entity remains retrievable unless permanently deleted.
* **Record restored → operational state reactivated:** Restoring an archived space.vars.entity returns it to active status without altering stored values or historical context.
***
## Data Structure
The space.vars.entities Data Model organizes operational data around several structural components that govern how space.vars.entities store values, relate to other space.vars.entities, and behave within the system.
### Record Fields
Each space.vars.entity stores field values defined by its space.vars.object’s schema.
Fields determine what data can exist on a space.vars.entity and how that data behaves.
* **System fields** provide identifiers, timestamps, ownership metadata, and lifecycle tracking.
* **Custom fields** capture business-specific data and may include validation rules, selectable options, relationships, or calculated values.
Field types influence:
* Validation and allowable values
* space.vars.automation triggers
* Reporting and filtering
* Integration payload structure
Schema-aware integrations must account for field configuration and data type behavior.
For detailed configuration guidance, see [Custom Fields](/docs/concepts/objects/custom-fields.md).
### Record Relationships
space.vars.entities relate across space.vars.objects through defined relationships that enable coordinated data behavior.
Relationships may represent:
* Parent-child structures
* Many-to-many connections
* Operational dependencies
Relational modeling allows organizations to:
* Link policies to claims
* Associate accounts with contacts
* Connect assets to locations
* Tie projects to milestones
Relationships support navigation, structured reporting, workflow coordination, cross-space.vars.object space.vars.automations, and inherited access evaluation. When modeling relationships, consider long-term scalability, reporting needs, and permission implications.
For configuration guidance, see [Object Relationships](/docs/concepts/objects/object-configuration/object-relationships.md).
### Record Governance & Permissions
The platform enforces structural safeguards that govern space.vars.entity behavior and protect data integrity.
Examples include:
* Uniqueness requirements within space.vars.object scope
* Required field enforcement
* Permission-based action constraints
* Action constraints such as archiving and restoration permissions
* License-based limits on space.vars.entity volume per space.vars.object
These constraints maintain consistency, enforce validation, and ensure predictable operational behavior at scale.
For more information, see [Record Permissions](/docs/concepts/objects/records/record-permissions.md)**.**
***
## Schemas
space.vars.entity behavior is governed by the space.vars.object schema, which defines how data is validated, structured, and enforced across space.vars.entity operations.
## The EntityRecordAddRequest object
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"EntityRecordAddRequest":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/FieldRequest"}},"unarchive":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/UnarchiveEnum"},{"$ref":"#/components/schemas/NullEnum"}]}},"required":["fields"]},"FieldRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid","nullable":true,"description":"ID of the field, can be used instead of field name."},"name":{"type":"string","nullable":true,"minLength":1,"description":"Name of the field, can be used instead of field ID."},"value":{"type":"object","additionalProperties":{},"nullable":true,"description":"Value to be set, this is required for fields that do not allow multiple values."},"add_values":{"type":"array","items":{},"nullable":true,"description":"Values to be added, applicable only for fields that allow multiple values."},"remove_values":{"type":"array","items":{},"nullable":true,"description":"Values to be removed, applicable only for fields that allow multiple values."}}},"UnarchiveEnum":{"enum":["prompt","unarchive","overwrite"],"type":"string","description":"* `prompt` - prompt\n* `unarchive` - unarchive\n* `overwrite` - overwrite"},"NullEnum":{"enum":[null]}}}}
```
## The EntityRecordDetail object
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"EntityRecordDetail":{"type":"object","properties":{"object_type":{"type":"string"},"num_upcoming_activities":{"type":"integer"},"fields":{"$ref":"#/components/schemas/Fields"},"id":{"type":"string","format":"uuid"},"client_info":{"$ref":"#/components/schemas/ClientInfo"},"access":{"$ref":"#/components/schemas/AccessSerpy"},"num_associated_team_members":{"type":"integer"},"lead_source_types":{"type":"array","items":{"$ref":"#/components/schemas/LeadSourceType"}}},"required":["access","client_info","fields","id","lead_source_types","num_associated_team_members","num_upcoming_activities","object_type"]},"Fields":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SerializedFieldValueDict"}},"required":["id"]},"SerializedFieldValueDict":{"type":"object","properties":{"id":{"type":"string"},"field_type":{"type":"string"},"display_name":{"type":"string"},"value":{"type":"object","additionalProperties":{}}},"required":["display_name","field_type","id","value"]},"ClientInfo":{"type":"object","properties":{"num_addresses_v2":{"type":"integer"},"display_name":{"type":"string"},"email_on_suppression_list":{"type":"boolean"}},"required":["display_name","email_on_suppression_list","num_addresses_v2"]},"AccessSerpy":{"type":"object","properties":{"view":{"type":"boolean"},"edit":{"type":"boolean"},"remove":{"type":"boolean"}},"required":["edit","remove","view"]},"LeadSourceType":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/ValueEnum"},"label":{"type":"string"}},"required":["label","value"]},"ValueEnum":{"enum":["organic_search","direct_traffic","site_referral","facebook_ads","google_ads","social","paid_social","utm","custom"],"type":"string","description":"* `organic_search` - Organic Search\n* `direct_traffic` - Direct Traffic\n* `site_referral` - Site Referral\n* `facebook_ads` - Facebook Ads\n* `google_ads` - Google Ads\n* `social` - Social\n* `paid_social` - Paid Social\n* `utm` - UTM\n* `custom` - Custom"}}}}
```
## The EntityRecordList object
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"EntityRecordList":{"type":"object","properties":{"object_type":{"type":"string"},"fields":{"$ref":"#/components/schemas/Fields"},"id":{"type":"string","format":"uuid"},"client_info":{"$ref":"#/components/schemas/ClientInfo"},"access":{"$ref":"#/components/schemas/AccessSerpy"}},"required":["access","client_info","fields","id","object_type"]},"Fields":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SerializedFieldValueDict"}},"required":["id"]},"SerializedFieldValueDict":{"type":"object","properties":{"id":{"type":"string"},"field_type":{"type":"string"},"display_name":{"type":"string"},"value":{"type":"object","additionalProperties":{}}},"required":["display_name","field_type","id","value"]},"ClientInfo":{"type":"object","properties":{"num_addresses_v2":{"type":"integer"},"display_name":{"type":"string"},"email_on_suppression_list":{"type":"boolean"}},"required":["display_name","email_on_suppression_list","num_addresses_v2"]},"AccessSerpy":{"type":"object","properties":{"view":{"type":"boolean"},"edit":{"type":"boolean"},"remove":{"type":"boolean"}},"required":["edit","remove","view"]}}}}
```
## The EntityRecordUpdateRequest object
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"EntityRecordUpdateRequest":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/FieldRequest"}},"archived_conflict":{"nullable":true,"description":"Updates the identifier of matching archived record to not raise a conflict.\n\n* `overwrite` - overwrite","oneOf":[{"$ref":"#/components/schemas/ArchivedConflictEnum"},{"$ref":"#/components/schemas/NullEnum"}]}},"required":["fields"]},"FieldRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid","nullable":true,"description":"ID of the field, can be used instead of field name."},"name":{"type":"string","nullable":true,"minLength":1,"description":"Name of the field, can be used instead of field ID."},"value":{"type":"object","additionalProperties":{},"nullable":true,"description":"Value to be set, this is required for fields that do not allow multiple values."},"add_values":{"type":"array","items":{},"nullable":true,"description":"Values to be added, applicable only for fields that allow multiple values."},"remove_values":{"type":"array","items":{},"nullable":true,"description":"Values to be removed, applicable only for fields that allow multiple values."}}},"ArchivedConflictEnum":{"enum":["overwrite"],"type":"string","description":"* `overwrite` - overwrite"},"NullEnum":{"enum":[null]}}}}
```
## The EntityRecordUpsertRequest object
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"EntityRecordUpsertRequest":{"type":"object","properties":{"lookup_value":{"type":"string","minLength":1,"description":"Value to match the entity record (name for custom objects, email for contacts)."},"oncreate_unarchive":{"nullable":true,"description":"Behavior when creating and a matching archived record exists.\n\n* `prompt` - prompt\n* `unarchive` - unarchive\n* `overwrite` - overwrite","oneOf":[{"$ref":"#/components/schemas/OncreateUnarchiveEnum"},{"$ref":"#/components/schemas/NullEnum"}]},"onupdate_archived_conflict":{"nullable":true,"description":"Updates the identifier of matching archived record to not raise a conflict during update.\n\n* `overwrite` - overwrite","oneOf":[{"$ref":"#/components/schemas/OnupdateArchivedConflictEnum"},{"$ref":"#/components/schemas/NullEnum"}]}},"required":["lookup_value"]},"OncreateUnarchiveEnum":{"enum":["prompt","unarchive","overwrite"],"type":"string","description":"* `prompt` - prompt\n* `unarchive` - unarchive\n* `overwrite` - overwrite"},"NullEnum":{"enum":[null]},"OnupdateArchivedConflictEnum":{"enum":["overwrite"],"type":"string","description":"* `overwrite` - overwrite"}}}}
```
## The PatchedEntityRecordUpdateRequest object
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"PatchedEntityRecordUpdateRequest":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/FieldRequest"}},"archived_conflict":{"nullable":true,"description":"Updates the identifier of matching archived record to not raise a conflict.\n\n* `overwrite` - overwrite","oneOf":[{"$ref":"#/components/schemas/ArchivedConflictEnum"},{"$ref":"#/components/schemas/NullEnum"}]}}},"FieldRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid","nullable":true,"description":"ID of the field, can be used instead of field name."},"name":{"type":"string","nullable":true,"minLength":1,"description":"Name of the field, can be used instead of field ID."},"value":{"type":"object","additionalProperties":{},"nullable":true,"description":"Value to be set, this is required for fields that do not allow multiple values."},"add_values":{"type":"array","items":{},"nullable":true,"description":"Values to be added, applicable only for fields that allow multiple values."},"remove_values":{"type":"array","items":{},"nullable":true,"description":"Values to be removed, applicable only for fields that allow multiple values."}}},"ArchivedConflictEnum":{"enum":["overwrite"],"type":"string","description":"* `overwrite` - overwrite"},"NullEnum":{"enum":[null]}}}}
```
***
## Additional Information
Supported APIs
The following APIs support space.vars.entity data management:
* [Adding Records via API](/docs/concepts/objects/records/records-apis/add-records-api.md)
* [Manage Records by ID API](/docs/concepts/objects/records/records-apis/manage-records-by-id-api.md)
* [Retrieving a Record by Name or Email via API](/docs/concepts/objects/records/records-apis/manage-records-by-id-api.md#retrieve-a-record-schema)
* [Create or Update Records (Upsert) API](/docs/concepts/objects/records/records-apis/create-or-update-records-upsert-api.md)
See the API documentation for endpoint-level detail.
Error States
The Records Data Model may produce predictable error conditions such as:
* Duplicate identifier conflicts
* Identifier collisions during lookup or upsert
* Permission-related access failures
* Validation errors due to schema rules
Understanding these conditions helps anticipate operational constraints without requiring troubleshooting steps.
***
## What’s Next
Continue to [Record Permissions](/docs/concepts/objects/records/record-permissions.md) to understand how access is governed across space.vars.entities, or see any of the following topics below:
Related Topics
* [Records Core Concepts](/docs/concepts/objects/records/records-core-concepts.md)
* [Team Interactions in Records](/docs/concepts/objects/records/team-interactions-in-records.md)
* [Records Permissions](/docs/concepts/objects/records/record-permissions.md)
* [Records APIs](/docs/concepts/objects/records/records-apis.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.kizen.com/docs/concepts/objects/records/records-data-model.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.