Contacts Data Model
Audience: Admins, Developers, Solution Architects
Purpose: Explains how the Contacts data model works so you can confidently design schemas, integrations, automations, and permissions that correctly model people and communication behavior across the platform.
Overview
Contact Objects are a special kind of Object used when you want to represent people within the platform’s data model. While Contacts share many structural characteristics with standard Objects (fields, associations, permissions, APIs), they also introduce system-level behaviors specific to communication, consent, and messaging.
The Contacts data model exists to support:
Person-level identity and de-duplication
Communication workflows (email and SMS)
Consent and compliance logic
Relationship modeling between people and other Records
API and automation behaviors that depend on person-specific rules
Understanding the Contacts data model is critical for building reliable integrations, designing scalable schemas, and avoiding unintended communication or compliance issues.
How Contacts Are Identified
Contacts use a different identification model than standard Objects. This differs from standard Objects, where the Record name is the primary identifier.
Primary Identifier is different: The email address functions as the unique identifier for Contacts across the platform.
Two Contacts cannot share the same email address
Email is not required: The email address is not required to create a Contact, but:
At least one of the following must be present to create a contact: first name, last name, email, or mobile phone
Contacts created without email are more likely to produce duplicates during imports and integrations
Many Contact features such as emailing, subscription management, identification via API rely on having an email address
Email is editable: The email address can be edited even though it is a unique identifier. It works similar to renaming a Record name on an Object.
How Contacts Are Used
Use Contacts to model individual people within the data model.
Contacts support person-specific capabilities that are not available on standard Objects, including communication workflows, consent management, and identity-based behaviors. Contacts are appropriate when Records must be addressable by email, participate in messaging, trigger communication-based automations, or be referenced externally via APIs using person-level identifiers.
Modeling people as custom Objects instead of Contacts removes access to system features such as email and SMS delivery, subscription management, email status enforcement, Contact-specific automation triggers, and message history.
Practical Modeling Examples
Applicants
Yes
Applicants often need email communication, reminders, consent tracking, and follow-up automations.
Policyholders
Yes
Policyholders require communication, identity matching, and history across multiple policies.
Internal Roles (e.g., Underwriter role on a policy)
No
Represents a role or function, not a person you communicate with externally.
System-only entities (e.g., Scoring Profile, Risk Persona)
No
These represent data structures, not real people.
Data Structure
Contacts follow the same foundational data structure as standard Objects. Every Contact is composed of the same three core elements: fields, Records, and relationships. Together, these define both the structure of Contact data and how that data behaves across the system.
Contact Fields
Contact fields define the schema of the Contact Object. They determine what data can be stored on Contact Records and how that data is validated and used across the platform.
Contact Fields specify:
The type of data (text, number, date, select, relationship, etc.)
Whether the data is required, read-only, or conditional
How the data participates in automation, reporting, messaging, and integrations
Fields belong to the Contact Object, not to individual Records. Like standard Objects, Contacts rely on flexible, business-defined schemas rather than fixed predefined structures.
In addition to supporting all standard custom field types, Contacts also include system-managed fields that introduce specialized behavior, such as:
Email (unique identifier)
Email Status (consent and deliverability logic)
Tags (with tag manager behavior)
Messaging-related fields
Time zone
These fields affect not only validation but also how Contacts behave in communication workflows.
For more information, see Custom Fields.
Records
Contact Records are the actual instances of data created using the Contact schema.
Each Contact Record:
Stores field values
Represents a real person
Can be related to other Contacts and other Objects
Can participate in messaging, automations, APIs, and permissions
While the Contact Object defines structure and fields define validation rules, Contact Records contain the actual stored data.
Schema changes affect how future updates are validated but do not retroactively modify existing Contact data unless explicitly written by an automation, integration, or user action.
For more information, see Records.
Relationships
Contacts use the same relationship model as standard Objects.
Relationships define how Contact Records connect to:
Other Contacts
Records in other Objects
They are implemented as a specialized field type and always connect Record to Record, not Object to Object.
Relationships enable:
Linking people to accounts, cases, applications, or other business data
Cross-record automation behavior
Reporting across connected Records
Collaboration without relying on ownership
A relationship is defined at the Object level as a field, but its value is stored on individual Contact Records as a reference to another Record.
When a relationship field is created, an inverse relationship field is automatically created on the related Object. Updates are reflected on both sides, enabling bi-directional navigation between related Records.
Contacts intentionally do not support an Owner field. Visibility and collaboration are managed through relationships and permissions rather than ownership.
For more information, see Object Relationships.
How These Pieces Work Together
Contacts follow the same structural model as standard Objects:
Objects define schema
Fields and relationships define structure and rules
Records store actual values that conform to that schema
The difference is not in structure, but in behavior. Contacts introduce additional system-level logic on top of this shared model to support communication, identity, consent, and compliance.
This allows Contacts to remain fully compatible with the platform’s data model, APIs, automations, and integrations while safely supporting person-specific workflows.
Schemas
Contacts use the same schema model as standard Objects. They support the same combination of system fields, default fields, and admin-defined custom fields. This schema determines what data can exist on a Contact, how that data behaves across the platform, what information is available to automations and APIs, and which fields appear throughout the UI and integrations.
For a detailed explanation of how these schemas are defined and managed, see the Schema section of the Objects Data Model topic.
Contact Relationships
Contacts use the same relationship system as standard Objects, which means they can be connected to other Records in meaningful, structured ways rather than existing in isolation.
Contacts can be related to:
Other Contacts (for example, spouses, coworkers, household members)
Records in other Objects (such as Accounts, Policies, Tickets, Applications, or Projects)
These relationships are not just visual links. They directly influence:
What data users can see
How Records appear in timelines and dashboards
How automations behave across connected Records
How reporting works across related data
Because Contacts do not have an Owner field, relationships and permissions are the primary mechanisms for collaboration and visibility. Instead of assigning a person to a single owner, organizations model real-world structure through associations.
This makes it possible to model patterns like:
A household with multiple related Contacts
A single Contact linked to multiple Accounts or Policies
A Contact holding multiple roles across different Records
Complex many-to-many relationships between people and business data
In practice, this means Contacts behave like first-class Records in your data model, fully connected to the rest of your system rather than siloed as standalone profiles.
For more information on Relationships and Associations, see Object Relationships.
Contact Fields
Contacts support the same field model as standard Objects, including system fields, default fields, and custom fields.
For general field behavior, creation, and configuration, see Custom Fields. This section focuses only on fields that have Contact-specific behavior.
Contact-Specific Fields
Some fields on Contacts introduce platform behavior that does not exist on standard Objects:
First Name: Used for personalization in communications, greetings, and templates. This field supports dynamic merge values and improves readability across the UI and reporting.
Last Name: Used alongside First Name to identify Contacts in the UI, search results, and reporting. This field is commonly required for communication workflows and external integrations.
Titles: Stores a Contact’s role or job title. This field is informational and commonly used for segmentation, reporting, and personalization in communications.
Email: Acts as the unique identifier for Contacts. Two Contacts cannot share the same email address. This affects imports, API lookups, de-duplication, and communication behavior.
Email Status: Controls consent and deliverability. Values such as Not Opted In, Opted In, Unsubscribed, and Suppressed directly affect whether a Contact can receive email. Suppressed status cannot be manually overridden.
Tags: Contacts include a system-promoted Tags field with a built-in Tag Manager. Tags can also trigger Contact-specific automation behavior.
Home Phone: Stores a personal phone number for reference or reporting. This field does not drive messaging or automation behavior.
Business Phone: Stores a work phone number for reference or reporting. This field is informational and does not support SMS delivery.
Mobile Phone: Used specifically for SMS messaging when texting is enabled. Other phone fields are informational only.
Time Zone: Stores a Contact’s time zone for use in time-aware messaging and scheduling behavior.
These fields do not just store data. They actively influence messaging, automation, compliance, and system behavior for Contacts.
Contact Rules
Contacts enforce several system-level rules that do not apply to standard Objects. These rules exist to support identity management, communication, and compliance.
System-Enforced Constraints
Email must be unique
Two Contacts cannot share the same email address.
Email functions as the Contact’s unique identifier for imports, APIs, de-duplication, and communication workflows.
Suppressed email is irreversible
Once an email is marked as Suppressed (e.g., due to spam complaints or repeated bounces), it cannot be re-enabled for that email address.
Prevents accidental violations of deliverability and compliance rules. This is a permanent state for that email value.
Restricted system fields
Certain system-managed fields (such as Email Status) cannot always be edited and may be locked by platform logic.
Ensures that consent, deliverability, and communication behavior cannot be bypassed manually.
Communication-gated permissions
Specific permissions control who can send email, send SMS, or manage subscriptions.
Protects against unauthorized messaging and enforces operational governance.
Fixed API identity
The Contacts Object API name cannot be changed, even via API.
Ensures consistent identity behavior across integrations and prevents breaking communication logic.
Caution: Some Contact behaviors are intentionally irreversible. Most notably, when an email address enters a suppressed state, it cannot be manually re-enabled for that email value. This protects system integrity, deliverability, and compliance.
For details on how permissions control access and messaging behavior, see Contact Permissions.
Additional Information
Supported APIs
Supported APIs
Contacts use the same API patterns as standard Object. For API information on Standard Objects, see the Object APIs topic.
Error States
Error States
Common Contact-specific error conditions include:
Attempting to create a Contact with an email that already exists
Import failures caused by missing identifiers
Messaging failures due to suppressed or unsubscribed status
API lookup failures when identifier does not resolve
Permission-based errors when accessing messaging features
These errors are not simply validation issues; many are caused by Contact-specific system rules.
What’s Next
Next, review Custom Fields to understand how individual field types, system fields, and custom fields can affect Contact behavior across the platform.
Last updated
Was this helpful?