Records Data Model
Audience: Developers, Solution Architects, Technical Integrators
Purpose: Explains how the Records Data Model structures, identifies, relates, and governs operational business data across the platform.
Overview
The Records define how operational business data is structured, identified, related, and governed across the platform.
This page defines the architectural components of Record management, including identifiers, field values, relationships, associations, and governing constraints. It builds on concepts introduced in Records Core Concepts.
How Records Are Identified
Every Record must have a unique identifier within its Object. This ensures Records can be reliably retrieved, updated, and referenced across workflows, reporting, and integrations.
Primary Identifiers
For most Objects, the Record Name serves as the primary identifier for each Record. It must be unique within the Object and is used in lookup, upsert, and integration scenarios.
For Contact Records, the primary identifier is email. Because Contacts are communication-oriented, email functions as both a contact and a unique identity key, while still operating within the same Record model.
API-Facing Identifiers
While Record names and email addresses function as primary business identifiers, the API uses system-generated identifiers for Record-level operations.
Record ID: System-generated at Record creation, immutable, and globally unique. Used for retrieve, update, and archive operations, and serves as the authoritative identifier in API interactions.
Object Identifier: Records are scoped within an Object and may be referenced using either the Object API name or the Object ID when performing API operations.
Lookup and Upsert Identifiers: Record Name is used for most Object Records, and email is used for Contact Records. These operations rely on 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 Record lifecycle governs how stored business data is created, modified, archived, and restored. Unlike Object lifecycle changes, Record lifecycle events operate directly on stored data.
Record created → data instance established: Creating a Record stores a new instance of structured data within an Object. At this stage, the Record receives a system-generated UUID and becomes subject to schema validation, permissions, and lifecycle tracking.
Record updated → values modified: Updating a Record 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 Record removes it from active operational views while preserving stored data and historical activity. The Record remains retrievable unless permanently deleted.
Record restored → operational state reactivated: Restoring an archived Record returns it to active status without altering stored values or historical context.
Data Structure
The Records Data Model organizes operational data around several structural components that govern how Records store values, relate to other Records, and behave within the system.
Record Fields
Each Record stores field values defined by its Object’s schema.
Fields determine what data can exist on a Record 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
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.
Record Relationships
Records relate across 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-object automation, and inherited access evaluation. When modeling relationships, consider long-term scalability, reporting needs, and permission implications.
For configuration guidance, see Object Relationships.
Record Governance & Permissions
The platform enforces structural safeguards that govern Record behavior and protect data integrity.
Examples include:
Uniqueness requirements within Object scope
Required field enforcement
Permission-based action constraints
Action constraints such as archiving and restoration permissions
License-based limits on Record volume per Object
These constraints maintain consistency, enforce validation, and ensure predictable operational behavior at scale.
For more information, see Record Permissions (Coming Soon).
Schemas
Record behavior is governed by the Object schema, which defines how data is validated, structured, and enforced across Record operations.
Additional Information
Supported APIs
The following APIs support Record data management:
Adding Records via API (Coming Soon)
Retrieving a Record by Name or Email via API (Coming Soon)
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 to understand how access is governed across Records, or see any of the following topics below:
Last updated
Was this helpful?