# Contacts Data Model

{% hint style="success" %}
**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.
{% endhint %}

## Overview

Contact <code class="expression">space.vars.objects</code> are a special kind of <code class="expression">space.vars.object</code> used when you want to represent people within the platform’s data model. While Contacts share many structural characteristics with standard <code class="expression">space.vars.objects</code> (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 <code class="expression">space.vars.entities</code>
* 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 <code class="expression">space.vars.objects</code>. This differs from standard <code class="expression">space.vars.objects</code>, where the <code class="expression">space.vars.entity</code> 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 <code class="expression">space.vars.entity</code> name on an <code class="expression">space.vars.object</code>.

***

## 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 <code class="expression">space.vars.objects</code>, including communication workflows, consent management, and identity-based behaviors. Contacts are appropriate when <code class="expression">space.vars.entities</code> 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 <code class="expression">space.vars.objects</code> 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

<table><thead><tr><th width="286.421875">Scenario</th><th width="144.8203125">Use Contacts?</th><th>Why</th></tr></thead><tbody><tr><td>Applicants</td><td>Yes</td><td>Applicants often need email communication, reminders, consent tracking, and follow-up automations.</td></tr><tr><td>Policyholders</td><td>Yes</td><td>Policyholders require communication, identity matching, and history across multiple policies.</td></tr><tr><td>Internal Roles (e.g., Underwriter role on a policy)</td><td>No</td><td>Represents a role or function, not a person you communicate with externally.</td></tr><tr><td>System-only entities (e.g., Scoring Profile, Risk Persona)</td><td>No</td><td>These represent data structures, not real people.</td></tr></tbody></table>

***

## Data Structure

Contacts follow the same foundational data structure as standard <code class="expression">space.vars.objects</code>. Every Contact is composed of the same three core elements: fields, <code class="expression">space.vars.entities</code>, and relationships. Together, these define both the structure of Contact data and how that data behaves across the system.

<div data-with-frame="true"><figure><img src="/files/tsrqMO22ORwBhpzHVdo7" alt="" width="563"><figcaption></figcaption></figure></div>

### Contact Fields

Contact fields define the schema of the Contact <code class="expression">space.vars.object</code>. They determine what data can be stored on Contact <code class="expression">space.vars.entities</code> 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 <code class="expression">space.vars.object</code>, not to individual <code class="expression">space.vars.entities</code>. Like standard <code class="expression">space.vars.objects</code>, 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](broken://pages/6rrJeEIzfjMAZY62pfmc).

### Records

Contact <code class="expression">space.vars.entities</code> are the actual instances of data created using the Contact schema.

Each Contact <code class="expression">space.vars.entity</code>:

* Stores field values
* Represents a real person
* Can be related to other Contacts and other <code class="expression">space.vars.objects</code>
* Can participate in messaging, automations, APIs, and permissions

While the Contact <code class="expression">space.vars.object</code> defines structure and fields define validation rules, Contact <code class="expression">space.vars.entities</code> 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](/docs/concepts/objects/records.md).

### Relationships

Contacts use the same relationship model as standard <code class="expression">space.vars.objects</code>.

Relationships define how Contact <code class="expression">space.vars.entities</code> connect to:

* Other Contacts
* <code class="expression">space.vars.entities</code> in other <code class="expression">space.vars.objects</code>

They are implemented as a specialized field type and always connect <code class="expression">space.vars.entity</code> to <code class="expression">space.vars.entity</code>, not <code class="expression">space.vars.object</code> to <code class="expression">space.vars.object</code>.

Relationships enable:

* Linking people to accounts, cases, applications, or other business data
* Cross-record automation behavior
* Reporting across connected <code class="expression">space.vars.entities</code>
* Collaboration without relying on ownership

A relationship is defined at the <code class="expression">space.vars.object</code> level as a field, but its value is stored on individual Contact <code class="expression">space.vars.entities</code> as a reference to another <code class="expression">space.vars.entity</code>.

When a relationship field is created, an inverse relationship field is automatically created on the related <code class="expression">space.vars.object</code>. Updates are reflected on both sides, enabling bi-directional navigation between related <code class="expression">space.vars.entities</code>.

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](/docs/concepts/objects/object-configuration/object-relationships.md).

### How These Pieces Work Together

Contacts follow the same structural model as standard <code class="expression">space.vars.objects</code>:

* <code class="expression">space.vars.objects</code> define schema
* Fields and relationships define structure and rules
* <code class="expression">space.vars.entities</code> 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 <code class="expression">space.vars.objects</code>. 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.&#x20;

For a detailed explanation of how these schemas are defined and managed, see the [Schema](/docs/concepts/objects/object-data-model.md#schemas) section of the [Objects Data Model](/docs/concepts/objects/object-data-model.md) topic.

***

### Contact Relationships

Contacts use the same relationship system as standard <code class="expression">space.vars.objects</code>, which means they can be connected to other <code class="expression">space.vars.entities</code> in meaningful, structured ways rather than existing in isolation.

Contacts can be related to:

* Other Contacts (for example, spouses, coworkers, household members)
* <code class="expression">space.vars.entities</code> in other <code class="expression">space.vars.objects</code> (such as Accounts, Policies, Tickets, Applications, or Projects)

These relationships are not just visual links. They directly influence:

* What data users can see
* How <code class="expression">space.vars.entities</code> appear in timelines and dashboards
* How automations behave across connected <code class="expression">space.vars.entities</code>
* 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 <code class="expression">space.vars.entities</code>
* Complex many-to-many relationships between people and business data

In practice, this means Contacts behave like first-class <code class="expression">space.vars.entities</code> 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](/docs/concepts/objects/object-configuration/object-relationships.md).

***

## Contact Fields

Contacts support the same field model as standard <code class="expression">space.vars.objects</code>, including system fields, default fields, and custom fields.

For general field behavior, creation, and configuration, see [Custom Fields](broken://pages/6rrJeEIzfjMAZY62pfmc). 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 <code class="expression">space.vars.objects</code>:

* **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 <code class="expression">space.vars.objects</code>. These rules exist to support identity management, communication, and compliance.

#### System-Enforced Constraints

| Rule                                 | What It Means                                                                                                                               | Why It Matters                                                                                                         |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **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 <code class="expression">space.vars.object</code> API name cannot be changed, even via API.                                    | Ensures consistent identity behavior across integrations and prevents breaking communication logic.                    |

{% hint style="warning" %}
**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.
{% endhint %}

For details on how permissions control access and messaging behavior, see [Contact Permissions](broken://pages/ZfSbXfWgUab5oeBMU2jp).

***

## Additional Information

<details>

<summary>Supported APIs</summary>

#### Supported APIs

Contacts use the same API patterns as standard <code class="expression">space.vars.object</code>. For API information on Standard <code class="expression">space.vars.objects</code>, see the [Object APIs](/docs/concepts/objects/object-apis.md) topic.

</details>

<details>

<summary>Error States</summary>

#### 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.

</details>

***

## What’s Next

Next, review [Custom Fields](broken://pages/6rrJeEIzfjMAZY62pfmc) to understand how individual field types, system fields, and custom fields can affect Contact behavior across the platform.

<details>

<summary>Related Topics</summary>

* [Contacts](/docs/concepts/objects/contacts.md)
* [Contacts Core Concepts](/docs/concepts/objects/contacts/contacts-core-concepts.md)
* [Contact Permissions](/docs/concepts/objects/contacts/contact-permissions.md)
* [Objects](/docs/concepts/objects.md)
* [Records](/docs/concepts/objects/records.md)
* [Custom Fields](broken://pages/6rrJeEIzfjMAZY62pfmc)

</details>


---

# 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/contacts/contacts-data-model.md?ask=<question>
```

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.