# Object Data Model {% hint style="success" %} **Audience:** Developers and Solution Architects **Purpose:** Explains how space.vars.objects are structured in space.vars.Kizen\_company\_name, including how space.vars.entitys, fields, identifiers, and relationships behave across the platform. {% endhint %} ## Overview space.vars.objects define the canonical data structures used across space.vars.Kizen\_company\_name to store, relate, and operate on business data. They provide the schema layer that governs how space.vars.entities are created, validated, related, and accessed. This page defines the space.vars.objects data model, including space.vars.object definitions, space.vars.entity instances, fields, identifiers, and relationship mechanics. It builds on concepts introduced in the [Object Core Concepts](/docs/concepts/objects/object-core-concepts.md). ### How Objects Are Identified space.vars.objects and space.vars.entities in space.vars.Kizen\_company\_name 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, space.vars.automations, and data imports. #### System-Generated Identifiers space.vars.Kizen\_company\_name assigns immutable, system-generated IDs that uniquely identify data within a Business. These identifiers form the canonical identity layer of the platform. Every space.vars.object and space.vars.entity 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 space.vars.object definition. It is used internally by the platform and APIs to reference the space.vars.object’s schema and configuration. **What it identifies** * The space.vars.object’s schema * Field definitions * Relationship definitions * Configuration type (Standard or Workflow) **What it’s used for** * Retrieving or describing space.vars.object schemas * Determining which fields and relationships exist * Applying validation rules to space.vars.entities * Driving configuration-dependent behavior in APIs and space.vars.automations **Key characteristics** * **Schema-level**: identifies the structure, not the data * **Stable**: does not change if the space.vars.object is renamed * **System-generated:** typically represented as a UUID-style identifier #### What Is A `record_id` ? A `record_id` uniquely identifies a single space.vars.entity instance that belongs to an space.vars.object. **What it identifies** * One specific data space.vars.entity (for example, a single policy, ticket, or claim) * The stored field values for that space.vars.entity * References to related space.vars.entities **What it’s used for** * Creating, retrieving, updating, or deleting space.vars.entities * Linking space.vars.entities through relationships * Displaying data in timelines, dashboards, and reports * Triggering space.vars.automations based on space.vars.entity-level events **Key characteristics** * **Instance-level**: it identifies data, not structure * **Stable**: it does not change if field values or display names change The 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, space.vars.automations, and space.vars.timelines. ### API-Facing Identifiers In addition to system-generated IDs, space.vars.Kizen\_company\_name exposes API-facing identifiers. In API requests, space.vars.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, space.vars.automations, and imports * Allow space.vars.entities 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 space.vars.object lifecycle governs how a space.vars.object’s schema is created, evolved, and eventually retired. This lifecycle affects how space.vars.entities are validated and interpreted, but it does not directly manipulate stored data. * **Object created → schema defined:** Creating an space.vars.object establishes a new schema, including its fields, relationships, configuration type (Standard or Workflow), and validation rules. At this stage, no space.vars.entities exist, only the structure they will conform to. * **Schema modified → validation rules updated:** Changes to an space.vars.object—such as adding fields, updating required rules, or modifying relationships—updates the schema that governs future space.vars.entity writes. These changes affect how new or updated space.vars.entities are validated but do not automatically alter existing stored values. * **Object deleted → schema removed:** Deleting an space.vars.object permanently removes the space.vars.object schema and deletes all associated Records. This cannot be undone. Schema changes apply uniformly across all space.vars.entities for an object. Field types are immutable, and existing field values are not changed unless a space.vars.entity is explicitly updated. *** ## Data Structure Every space.vars.object is composed of three core elements: fields, relationships, and space.vars.entities. Together, these define both the structure of the data and how data behaves across the system.
### Custom Fields space.vars.fields define the schema of an space.vars.object. They determine what data can be stored on space.vars.entities 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 space.vars.automations, reporting, integrations, and UI behavior space.vars.fields belong to the space.vars.object, not to individual space.vars.entities. space.vars.objects support dynamic, business-defined schemas, allowing each organization to extend its data model without requiring code changes. Each newly created space.vars.object includes several system fields that cannot be removed, including: * \ Name * Owner * Display Name * Date Created * Last Modified space.vars.objects with space.vars.workflow enabled also include Stage, Estimated Close Date, and Actual Close Date. For space.vars.objects, Name and Owner are the only required fields (Stage is also required when space.vars.workflow is enabled). All other fields, including space.vars.fields, are optional. Contact records follow the same model but include additional required fields because they function as unique identity space.vars.entities. space.vars.fields and relationships define schema only. They do not store data themselves. For more information, see [Custom Fields](/docs/concepts/objects/custom-fields.md). ### Records space.vars.entities are the actual instances of data created using an space.vars.object’s schema. Each space.vars.entity: * Stores field values * Represents a real-world entity (such as a policy, ticket, client, or claim) * Can be related to other space.vars.entities While space.vars.objects define structure and fields define validation rules, space.vars.entities contain the actual data. space.vars.entity data is stored as a set of field values, where each value is associated with a specific field definition and validated against the space.vars.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](/docs/concepts/objects/records.md). ### Relationships Relationships define how space.vars.entitys connect to one another across space.vars.objects. They are implemented as a specialized field type and always connect space.vars.entity to space.vars.entity, not space.vars.object to space.vars.object. Relationships enable: * Linking related business data (for example, a policy to a contact, or a claim to a policy) * Cross-space.vars.object space.vars.automations and updates, including between space.vars.entities of the same space.vars.object * Accurate reporting across connected space.vars.entities A relationship is defined at the space.vars.object level as a field, but its value is stored on individual Records as a reference to another space.vars.entity. 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 space.vars.object. space.vars.entity-level updates to a relationship are reflected on both sides, enabling bi-directional navigation between related space.vars.entities. For more information, [Object Relationships](/docs/concepts/objects/object-configuration/object-relationships.md). ### How These Pieces Work Together space.vars.objects define schema. Custom Fields and relationships describe structure and rules. space.vars.entities store values that conform to that schema, including references to other space.vars.entities through relationship fields.
This separation between schema metadata and space.vars.entity data allows space.vars.objects to evolve independently of stored values while supporting reliable validation, space.vars.automations, and scalable integrations across the platform. *** ## Object Configurations All space.vars.objects share a common architectural foundation, but differ in behavior depending on how they are configured. Understanding the different space.vars.object configurations is critical when designing data models, space.vars.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 space.vars.field types and relationships * Are fully accessible through space.vars.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
space.vars.workflow configurations are used to model space.vars.entities 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 space.vars.workflow when its primary purpose is to coordinate process execution or track a business asset as it progresses through a defined set of stages, rather than represent a static business space.vars.entity. space.vars.workflow configurations: * Include all capabilities of Standard configurations, including space.vars.fields, relationships, space.vars.automations, and API access * Support defined stages to represent lifecycle progression or process steps * Support board views for visual management * Enable stage-based space.vars.automations * Power space.vars.dashboards, operational reporting, and analytics * Support value tracking and percent chance to close when enabled space.vars.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 space.vars.entities such as deals, tickets, applications, renewals, onboarding flows, claims, projects, cases, implementations, escalations, compliance reviews, and service delivery. Use a space.vars.workflow configuration when records move through defined stages, stage transitions drive space.vars.automations, 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 space.vars.workflow configuration has significant architectural consequences. It determines which system-managed fields exist on an space.vars.object, how space.vars.entities participate in lifecycle-driven features, how space.vars.automations execute, and whether data can be used in dashboards, forecasting, and stage-based reporting. space.vars.workflow configurations include additional system-managed fields—such as **Stage** and **Percent Chance to Close**—that are intrinsic to the space.vars.workflow model. These capabilities cannot be added to Standard configurations after the fact. Choosing the wrong configuration often requires recreating the space.vars.object to enable workflow-specific behavior. Configuration choice also affects space.vars.automation timing, event behavior, relationship design, and long-term scalability. Relationships introduced early in a data model can create dependencies across space.vars.objects that are difficult to reverse without significant refactoring. #### API Implications Standard and space.vars.workflow configurations use different endpoint families, expose different system-managed fields, and enforce different validation rules. Integrations must account for an space.vars.object’s configuration when constructing requests, handling responses, and designing space.vars.automation space.vars.workflows. *** ## Schemas ### Object Schema The space.vars.object schema defines the structure and behavior of a space.vars.object in space.vars.Kizen\_company\_name. It describes the schema-level configuration that governs how space.vars.entities are created, validated, related, and accessed across the platform. ## The CustomObjectDetail object ```json {"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"CustomObjectDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"object_type":{"$ref":"#/components/schemas/ObjectTypeEnum"},"entity_name":{"type":"string","maxLength":200},"object_name":{"type":"string","maxLength":200},"has_commerce_data":{"type":"boolean","default":false},"default_on_activities":{"type":"boolean"},"owner":{"allOf":[{"$ref":"#/components/schemas/SerializerMeta"}],"readOnly":true},"name":{"type":"string"},"description":{"type":"string","nullable":true,"maxLength":500},"ai_description":{"type":"string","readOnly":true,"nullable":true},"is_custom":{"type":"boolean","readOnly":true},"fetch_url":{"type":"string","readOnly":true},"allow_relations":{"type":"boolean","readOnly":true},"meta":{"type":"object","additionalProperties":{}},"related_objects":{"type":"array","items":{"$ref":"#/components/schemas/CustomObjectRelatedObjects"}},"created":{"type":"string","format":"date-time","readOnly":true},"access":{"allOf":[{"$ref":"#/components/schemas/AccessSerpy"}],"readOnly":true},"entity_access":{"type":"boolean","readOnly":true},"rollup_related_leadsources":{"type":"boolean","nullable":true},"quick_filtering_enabled":{"type":"boolean","nullable":true},"record_layouts":{"type":"array","items":{"$ref":"#/components/schemas/EmbeddedRecordLayout"},"readOnly":true},"association_source":{"$ref":"#/components/schemas/AssociationSourceEnum"},"association_source_fields":{"type":"array","items":{"$ref":"#/components/schemas/AssociationSourceField"},"nullable":true},"field_categories":{"type":"array","items":{"$ref":"#/components/schemas/FieldCategory"},"readOnly":true},"fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomObjectDetailedFieldRead"},"readOnly":true},"pipeline":{"allOf":[{"$ref":"#/components/schemas/CustomObjectPipeline"}],"readOnly":true},"browser_js_actions":{"type":"array","items":{"$ref":"#/components/schemas/BrowserJSAction"},"readOnly":true},"browser_route_scripts":{"type":"array","items":{"$ref":"#/components/schemas/BrowserRouteScript"},"readOnly":true},"custom_actions":{"type":"array","items":{"$ref":"#/components/schemas/CustomActionRead"},"readOnly":true}},"required":["access","ai_description","allow_relations","browser_js_actions","browser_route_scripts","created","custom_actions","default_on_activities","entity_access","entity_name","fetch_url","field_categories","fields","id","is_custom","object_name","owner","pipeline","record_layouts"]},"ObjectTypeEnum":{"enum":["pipeline","standard"],"type":"string","description":"* `pipeline` - pipeline\n* `standard` - standard"},"SerializerMeta":{"type":"object","properties":{"picture_url":{"type":"string"},"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"display_name":{"type":"string"},"account_type":{"type":"string"}},"required":["account_type","display_name","email","first_name","id","last_name","picture_url"]},"CustomObjectRelatedObjects":{"type":"object","properties":{"related_object":{"type":"string","format":"uuid"},"relation_type":{"$ref":"#/components/schemas/CustomObjectRelatedObjectsRelationTypeEnum"},"rollup_timeline":{"type":"boolean","default":false},"rollup_leadsources":{"type":"boolean","default":true},"object_type":{"type":"string","readOnly":true},"object_name":{"type":"string","readOnly":true},"entity_name":{"type":"string","readOnly":true},"field_id":{"type":"string","format":"uuid","nullable":true}},"required":["entity_name","object_name","object_type","related_object","relation_type"]},"CustomObjectRelatedObjectsRelationTypeEnum":{"enum":["one_to_one","primary","additional"],"type":"string","description":"* `one_to_one` - one to one\n* `primary` - primary\n* `additional` - additional"},"AccessSerpy":{"type":"object","properties":{"view":{"type":"boolean"},"edit":{"type":"boolean"},"remove":{"type":"boolean"}},"required":["edit","remove","view"]},"EmbeddedRecordLayout":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string"},"config":{"type":"object","additionalProperties":{}},"tabs":{"type":"object","additionalProperties":{}},"order":{"type":"number","format":"double"}},"required":["id","name"]},"AssociationSourceEnum":{"enum":["direct","related","direct_and_related"],"type":"string","description":"* `direct` - Direct\n* `related` - Related\n* `direct_and_related` - Direct and Related"},"AssociationSourceField":{"type":"object","description":"A serializer that accepts either an 'id' field or an alternate identifier field.\n\nThis serializer class automatically detects which identifier field is being used and\nperforms validation to ensure at least one identifier is provided. It also provides\nutility methods for retrieving objects by their identifiers.\n\nAttributes:\n IDENTIFIER_FIELD (str): The name of the alternate identifier field. Should be\n defined in subclasses.\n\nMethods:\n get_identifier_field(): Determines the alternate identifier field name.\n validate(attrs): Ensures either 'id' or the alternate identifier is provided.\n get_identifier_values(data, values_map, queryset): Retrieves objects by their identifiers.","properties":{"id":{"type":"string","format":"uuid","nullable":true,"description":"Required if \"name\" is not provided."},"name":{"type":"string","nullable":true,"description":"Required if \"id\" is not provided."},"related_field":{"type":"string","readOnly":true},"related_object":{"type":"string","readOnly":true}},"required":["related_field","related_object"]},"FieldCategory":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"order":{"type":"integer"}},"required":["id","name","order"]},"CustomObjectDetailedFieldRead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"category":{"type":"string","format":"uuid"},"display_name":{"type":"string"},"canonical_display_name":{"type":"string"},"is_default":{"type":"boolean"},"field_type":{"$ref":"#/components/schemas/FieldTypeEnum"},"is_required":{"type":"boolean"},"is_read_only":{"type":"boolean"},"is_hidden":{"type":"boolean"},"is_deletable":{"type":"boolean"},"is_hideable":{"type":"boolean"},"is_suppressed":{"type":"boolean"},"include_in_short_form":{"type":"string"},"allows_nulls":{"type":"boolean"},"allows_empty":{"type":"boolean"},"order":{"type":"integer"},"meta":{"type":"object","additionalProperties":{}},"description":{"type":"string"},"description_visibility":{"$ref":"#/components/schemas/DescriptionVisibilityEnum"},"properties":{"type":"object","additionalProperties":{}},"access":{"$ref":"#/components/schemas/AccessSerpy"},"options":{"type":"array","items":{"$ref":"#/components/schemas/FieldOptionSerpy"}},"relation":{"$ref":"#/components/schemas/CustomObjectFieldRelation"},"allow_on_forms":{"type":"boolean"}},"required":["access","allow_on_forms","allows_empty","allows_nulls","canonical_display_name","category","description","description_visibility","display_name","field_type","id","include_in_short_form","is_default","is_deletable","is_hidden","is_hideable","is_read_only","is_required","is_suppressed","meta","name","options","order","properties","relation"]},"FieldTypeEnum":{"enum":["checkbox","checkboxes","choices","date","datetime","decimal","dropdown","dynamictags","email","files","integer","longtext","money","phonenumber","radio","rating","relationship","selector","status","team_selector","text","timezone","wysiwyg","yesnomaybe"],"type":"string","description":"* `checkbox` - Checkbox\n* `checkboxes` - Checkboxes\n* `choices` - Choices\n* `date` - Date\n* `datetime` - Datetime\n* `decimal` - Decimal Number\n* `dropdown` - Dropdown\n* `dynamictags` - Dynamic Tags\n* `email` - Email\n* `files` - Files\n* `integer` - Whole Number\n* `longtext` - Long Text\n* `money` - Money\n* `phonenumber` - Phone Number\n* `radio` - Radio\n* `rating` - Rating\n* `relationship` - Relationship\n* `selector` - Selector\n* `status` - Status\n* `team_selector` - Team Selector\n* `text` - Text\n* `timezone` - Timezone\n* `wysiwyg` - Wysiwyg\n* `yesnomaybe` - Yes / No / Maybe Question"},"DescriptionVisibilityEnum":{"enum":["all","create_only","settings_only"],"type":"string","description":"* `all` - All Labels\n* `create_only` - Only on Create\n* `settings_only` - Only in Settings"},"FieldOptionSerpy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"name":{"type":"string"},"order":{"type":"integer"},"meta":{"type":"object","additionalProperties":{}},"percentage_chance_to_close":{"type":"integer"},"chance_to_close_percentage":{"type":"integer"},"status":{"$ref":"#/components/schemas/StatusEnum"}},"required":["chance_to_close_percentage","code","id","meta","name","order","percentage_chance_to_close","status"]},"StatusEnum":{"enum":["open","won","lost","disqualified"],"type":"string","description":"* `open` - open\n* `won` - won\n* `lost` - lost\n* `disqualified` - disqualified"},"CustomObjectFieldRelation":{"type":"object","properties":{"related_field":{"type":"string","format":"uuid","readOnly":true},"related_object":{"type":"string","format":"uuid"},"related_category":{"type":"string","format":"uuid","nullable":true},"related_name":{"type":"string","nullable":true},"related_object_name":{"type":"string","readOnly":true},"related_object_object_name":{"type":"string","readOnly":true},"related_entity_name":{"type":"string","readOnly":true},"relation_type":{"$ref":"#/components/schemas/CustomObjectFieldRelationRelationTypeEnum"},"cardinality":{"allOf":[{"$ref":"#/components/schemas/CardinalityEnum"}],"readOnly":true},"fetch_url":{"type":"string","readOnly":true},"rollup_timeline":{"type":"boolean"},"rollup_leadsources":{"type":"boolean"},"inverse_relation_rollup_timeline":{"type":"boolean"},"inverse_relation_rollup_leadsources":{"type":"boolean"},"inverse_relation_suppressed":{"type":"boolean"},"related_object_default_on_activities":{"type":"string","readOnly":true}},"required":["cardinality","fetch_url","related_category","related_entity_name","related_field","related_object","related_object_default_on_activities","related_object_name","related_object_object_name"]},"CustomObjectFieldRelationRelationTypeEnum":{"enum":["one_to_one","primary","additional","primary_for","additional_for"],"type":"string","description":"* `one_to_one` - one to one\n* `primary` - primary\n* `additional` - additional\n* `primary_for` - primary for\n* `additional_for` - additional for"},"CardinalityEnum":{"enum":["one_to_one","many_to_many","many_to_one","one_to_many"],"type":"string","description":"* `one_to_one` - 1 to 1\n* `many_to_many` - Many to Many\n* `many_to_one` - Many to 1\n* `one_to_many` - 1 to Many"},"CustomObjectPipeline":{"type":"object","properties":{"stages":{"type":"array","items":{"$ref":"#/components/schemas/PipelineStage"}},"track_entity_value":{"type":"boolean"},"include_percentage_to_close":{"type":"boolean"},"use_ai_to_update_percentage":{"type":"boolean"}},"required":["stages"]},"PipelineStage":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/StatusEnum"},"percentage_chance_to_close":{"type":"integer","maximum":100,"minimum":0,"nullable":true},"order":{"type":"integer","maximum":32767,"minimum":0}},"required":["name","order","status"]},"BrowserJSAction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"api_name":{"type":"string"},"name":{"type":"string"},"script":{"type":"string"},"plugin_app":{"$ref":"#/components/schemas/PluginAppLight"}},"required":["api_name","id","name","plugin_app","script"]},"PluginAppLight":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"api_name":{"type":"string"},"base_config":{"type":"object","additionalProperties":{}}},"required":["api_name","base_config","id"]},"BrowserRouteScript":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"api_name":{"type":"string"},"name":{"type":"string"},"routes":{"type":"object","additionalProperties":{}},"script":{"type":"string"},"blocking":{"type":"boolean"},"custom_object":{"$ref":"#/components/schemas/_CustomObject"},"plugin_app":{"$ref":"#/components/schemas/PluginAppLight"}},"required":["api_name","blocking","custom_object","id","name","plugin_app","routes","script"]},"_CustomObject":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"object_name":{"type":"string"}},"required":["id","name","object_name"]},"CustomActionRead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"action":{"type":"string"},"automation":{"$ref":"#/components/schemas/_CustomActionAutomation"},"order":{"type":"integer"}},"required":["action","automation","description","id","name","order"]},"_CustomActionAutomation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"api_name":{"type":"string"},"name":{"type":"string"}},"required":["api_name","id","name"]}}}} ``` ## The CustomObjectRead object ```json {"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"CustomObjectRead":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"object_type":{"$ref":"#/components/schemas/ObjectTypeEnum"},"entity_name":{"type":"string","maxLength":200},"object_name":{"type":"string","maxLength":200},"has_commerce_data":{"type":"boolean","default":false},"default_on_activities":{"type":"boolean"},"owner":{"allOf":[{"$ref":"#/components/schemas/SerializerMeta"}],"readOnly":true},"name":{"type":"string"},"description":{"type":"string","nullable":true,"maxLength":500},"ai_description":{"type":"string","readOnly":true,"nullable":true},"is_custom":{"type":"boolean","readOnly":true},"fetch_url":{"type":"string","readOnly":true},"allow_relations":{"type":"boolean","readOnly":true},"meta":{"type":"object","additionalProperties":{}},"related_objects":{"type":"array","items":{"$ref":"#/components/schemas/CustomObjectRelatedObjects"}},"number_of_records":{"type":"integer","readOnly":true},"created":{"type":"string","format":"date-time","readOnly":true},"access":{"allOf":[{"$ref":"#/components/schemas/AccessSerpy"}],"readOnly":true},"entity_access":{"type":"boolean","readOnly":true},"rollup_related_leadsources":{"type":"boolean","nullable":true},"quick_filtering_enabled":{"type":"boolean","nullable":true},"record_layouts":{"type":"array","items":{"$ref":"#/components/schemas/EmbeddedRecordLayout"},"readOnly":true},"association_source":{"$ref":"#/components/schemas/AssociationSourceEnum"},"association_source_fields":{"type":"array","items":{"$ref":"#/components/schemas/AssociationSourceField"},"nullable":true},"track_entity_value":{"type":"boolean"},"include_percentage_to_close":{"type":"boolean"},"use_ai_to_update_percentage":{"type":"boolean"},"ai_confidence_threshold":{"type":"string","format":"decimal","pattern":"^-?\\d{0,1}(?:\\.\\d{0,2})?$"},"pipeline":{"allOf":[{"$ref":"#/components/schemas/CustomObjectPipeline"}],"readOnly":true},"total_pipeline_value":{"type":"number","format":"double","readOnly":true},"total_commerce_value":{"type":"number","format":"double","readOnly":true},"reasons_lost":{"type":"array","items":{"$ref":"#/components/schemas/EmbededFieldOption"}},"reasons_disqualified":{"type":"array","items":{"$ref":"#/components/schemas/EmbededFieldOption"}},"undeletable_fields":{"type":"object","additionalProperties":{},"readOnly":true},"allow_on_forms":{"type":"boolean","nullable":true},"entity_display_name_pattern_text":{"type":"string"},"entity_display_name_pattern_html":{"type":"string"},"entity_search_text_pattern":{"type":"string"},"default_color":{"type":"string","default":"#085BEE"},"default_icon":{"type":"string","default":"bars-light"},"browser_js_actions":{"type":"array","items":{"$ref":"#/components/schemas/BrowserJSAction"},"readOnly":true},"browser_route_scripts":{"type":"array","items":{"$ref":"#/components/schemas/BrowserRouteScript"},"readOnly":true},"custom_actions":{"type":"array","items":{"$ref":"#/components/schemas/CustomActionRead"},"readOnly":true}},"required":["access","ai_description","allow_relations","browser_js_actions","browser_route_scripts","created","custom_actions","default_on_activities","entity_access","entity_name","fetch_url","id","is_custom","number_of_records","object_name","object_type","owner","pipeline","record_layouts","total_commerce_value","total_pipeline_value","undeletable_fields"]},"ObjectTypeEnum":{"enum":["pipeline","standard"],"type":"string","description":"* `pipeline` - pipeline\n* `standard` - standard"},"SerializerMeta":{"type":"object","properties":{"picture_url":{"type":"string"},"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"display_name":{"type":"string"},"account_type":{"type":"string"}},"required":["account_type","display_name","email","first_name","id","last_name","picture_url"]},"CustomObjectRelatedObjects":{"type":"object","properties":{"related_object":{"type":"string","format":"uuid"},"relation_type":{"$ref":"#/components/schemas/CustomObjectRelatedObjectsRelationTypeEnum"},"rollup_timeline":{"type":"boolean","default":false},"rollup_leadsources":{"type":"boolean","default":true},"object_type":{"type":"string","readOnly":true},"object_name":{"type":"string","readOnly":true},"entity_name":{"type":"string","readOnly":true},"field_id":{"type":"string","format":"uuid","nullable":true}},"required":["entity_name","object_name","object_type","related_object","relation_type"]},"CustomObjectRelatedObjectsRelationTypeEnum":{"enum":["one_to_one","primary","additional"],"type":"string","description":"* `one_to_one` - one to one\n* `primary` - primary\n* `additional` - additional"},"AccessSerpy":{"type":"object","properties":{"view":{"type":"boolean"},"edit":{"type":"boolean"},"remove":{"type":"boolean"}},"required":["edit","remove","view"]},"EmbeddedRecordLayout":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string"},"config":{"type":"object","additionalProperties":{}},"tabs":{"type":"object","additionalProperties":{}},"order":{"type":"number","format":"double"}},"required":["id","name"]},"AssociationSourceEnum":{"enum":["direct","related","direct_and_related"],"type":"string","description":"* `direct` - Direct\n* `related` - Related\n* `direct_and_related` - Direct and Related"},"AssociationSourceField":{"type":"object","description":"A serializer that accepts either an 'id' field or an alternate identifier field.\n\nThis serializer class automatically detects which identifier field is being used and\nperforms validation to ensure at least one identifier is provided. It also provides\nutility methods for retrieving objects by their identifiers.\n\nAttributes:\n IDENTIFIER_FIELD (str): The name of the alternate identifier field. Should be\n defined in subclasses.\n\nMethods:\n get_identifier_field(): Determines the alternate identifier field name.\n validate(attrs): Ensures either 'id' or the alternate identifier is provided.\n get_identifier_values(data, values_map, queryset): Retrieves objects by their identifiers.","properties":{"id":{"type":"string","format":"uuid","nullable":true,"description":"Required if \"name\" is not provided."},"name":{"type":"string","nullable":true,"description":"Required if \"id\" is not provided."},"related_field":{"type":"string","readOnly":true},"related_object":{"type":"string","readOnly":true}},"required":["related_field","related_object"]},"CustomObjectPipeline":{"type":"object","properties":{"stages":{"type":"array","items":{"$ref":"#/components/schemas/PipelineStage"}},"track_entity_value":{"type":"boolean"},"include_percentage_to_close":{"type":"boolean"},"use_ai_to_update_percentage":{"type":"boolean"}},"required":["stages"]},"PipelineStage":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/StatusEnum"},"percentage_chance_to_close":{"type":"integer","maximum":100,"minimum":0,"nullable":true},"order":{"type":"integer","maximum":32767,"minimum":0}},"required":["name","order","status"]},"StatusEnum":{"enum":["open","won","lost","disqualified"],"type":"string","description":"* `open` - open\n* `won` - won\n* `lost` - lost\n* `disqualified` - disqualified"},"EmbededFieldOption":{"type":"object","description":"Used in CustomObjectSerializer where we can create reasons_lost and reasons_disqualified","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["name"]},"BrowserJSAction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"api_name":{"type":"string"},"name":{"type":"string"},"script":{"type":"string"},"plugin_app":{"$ref":"#/components/schemas/PluginAppLight"}},"required":["api_name","id","name","plugin_app","script"]},"PluginAppLight":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"api_name":{"type":"string"},"base_config":{"type":"object","additionalProperties":{}}},"required":["api_name","base_config","id"]},"BrowserRouteScript":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"api_name":{"type":"string"},"name":{"type":"string"},"routes":{"type":"object","additionalProperties":{}},"script":{"type":"string"},"blocking":{"type":"boolean"},"custom_object":{"$ref":"#/components/schemas/_CustomObject"},"plugin_app":{"$ref":"#/components/schemas/PluginAppLight"}},"required":["api_name","blocking","custom_object","id","name","plugin_app","routes","script"]},"_CustomObject":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"object_name":{"type":"string"}},"required":["id","name","object_name"]},"CustomActionRead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"action":{"type":"string"},"automation":{"$ref":"#/components/schemas/_CustomActionAutomation"},"order":{"type":"integer"}},"required":["action","automation","description","id","name","order"]},"_CustomActionAutomation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"api_name":{"type":"string"},"name":{"type":"string"}},"required":["api_name","id","name"]}}}} ``` ### Record Schema The space.vars.entity schema represents an individual data instance that conforms to an space.vars.object’s schema. It contains the stored field values, system-managed metadata, and references to related space.vars.entities. ## 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]}}}} ``` For more information see, [Records Data Model](/docs/concepts/objects/records/records-data-model.md). *** ## Additional Information
Supported APIs #### Supported APIs space.vars.objects support APIs for: * [Retrieving Object Field Options](/docs/concepts/objects/custom-fields/custom-field-apis/retrieve-object-field-options-api.md) * [Retrieving Custom Object Details by ID](/docs/concepts/objects/object-apis/retrieve-object-details-by-id-api.md) * [Managing your Records](/docs/concepts/objects/records/records-apis/manage-records-by-id-api.md) 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](/docs/concepts/objects/object-apis.md) to see how this data model is used in real API requests and responses.
Related Topics * [Object Core Concepts](/docs/concepts/objects/object-core-concepts.md) * [Object Relationships](/docs/concepts/objects/object-configuration/object-relationships.md) * [Object Workflows](/docs/concepts/objects/object-configuration/object-workflows.md) * [Object Permissions](/docs/concepts/objects/object-configuration/object-permissions.md) * [Objects APIs](/docs/concepts/objects/object-apis.md)
--- # Agent Instructions: 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/object-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.