Contacts

The unified record of a person — built from identifiers across touchpoints, organized by profiles, and grouped into organizations.

Overview

A Contact is the unified record of a person, and the core object of Customer Data. CXF resolves the same person across channels and devices into one contact through identifiers, gives it structure through Profiles, and groups it under an Organization. Contacts also carry taxonomies, tags, relationships, workflows, ownership, archive, and segment membership. For the bigger picture, see the Customer Data overview.

Where to find it

Contacts live under Customer Data → Contacts.

Contact types

A contact’s type is computed automatically from its identifiers, name, and vendor flag — you don’t set it by hand:

Type	What it means
Ghost	Anonymous or unidentified — only an anonymous token, or missing a name. Created when someone interacts before identifying themselves.
Lead	Has a name and at least one email or phone, but none validated yet.
Contact	Has a name and at least one validated email or phone.
Vendor	A contact marked as a vendor (a supplier), regardless of validation.

Identifiers

An identifier is a value that identifies a contact — an email, a phone number, a UUID, an OAuth token, and so on. Identity resolution consolidates a person’s many identifiers into a single contact, so you have one 360° record instead of fragments.

Each identifier carries:

Property	Description
semantic_type	The kind of identifier — email, phone, oauth, uuid, …
identifier	The value itself (e.g. [e-mail]).
slug	A label within its type — Main, Work, Personal. Replaces a single “main” flag.
is_validated	Whether the value has been verified, and how/when (OTP, magic link, manual).
source	Where it came from (event data, import, manual).
outreach	Whether it’s a contact method you can reach out through.

An identifier’s slug is unique per semantic type per contact — a contact can’t have two Work emails, but can have a Work email and a Work phone. Every type has a Main slug (which can’t be removed); the contact’s primary email and phone resolve from it. The slug catalog is configured in Settings → Customer Data → Manage Identifiers.

Properties

Property	Type	Required	Description
given_name	string	Conditional	First name — required for a contact to be more than a ghost.
last_name	string	Conditional	Last name — required for a contact to be more than a ghost.
identifiers	array	No	The contact’s identifiers.
email	string	Auto	Primary email, resolved from the Main email identifier.
phone	string	Auto	Primary phone, resolved from the Main phone identifier.
is_vendor	boolean	No	Marks the contact as a vendor.
type	enum	Auto	Computed: ghost, lead, contact, or vendor.
organization_id	reference	No	The organization the contact belongs to.
profiles	array	No	Adopted profiles — drive the contact’s attributes.
segments	array	Auto	The segments the contact currently matches.

A contact’s custom fields come from the profiles it adopts; taxonomies, tags, and ownership apply as on any customer-data object.

How contacts are created

• Ghost — created automatically when an anonymous visitor interacts (a funnel, a chat widget, a web channel). The ghost is tracked by an anonymous token.
• Lead / full registration — a public sign-up creates a lead (name + email/phone, no validation yet) or a full registration (with a password). Validating an identifier promotes a lead to a contact.
• Admin — a user creates a contact directly from the dashboard.

When a known token is present, registering upgrades the existing ghost instead of creating a duplicate.

Behaviour & rules

• Type is derived, not set — it recomputes from the contact’s name, identifiers, and vendor flag.
• Validation promotes — a lead becomes a contact when one of its identifiers is validated (OTP or magic link).
• Belongs to one organization — setting organization_id groups the contact; renaming the organization updates the contact’s denormalized organization name.
• Ghost cleanup — ghost contacts can be auto-deleted after a period of inactivity, configured in Customer Data Settings.

Seeds

Contacts travel between environments as structural Seeds. A contact carries its name, identifiers, attribute values, adopted profiles (by slug), and a reference to its organization (resolved with a reference helper):

[
  {
    "object_type": "contacts",
    "data": {
      "given_name": "Roslyn",
      "last_name": "Hill",
      "organization_id": "{{getRecordAttribute('organizations', 'slug', 'lehner-plc')}}",
      "identifiers": [
        {
          "identifier": "[phone]",
          "semantic_type": "phone",
          "slug": "main",
          "source": "import",
          "validation_method": "manual",
          "is_validated": true,
          "outreach": true
        }
      ],
      "default": {
        "pet_name": "Rosie",
        "favorite_book": "The Hobbit"
      },
      "profiles": ["financial-profile", "sales-profile"],
      "is_vendor": false
    }
  }
]

The contact’s attribute values live under their attribute group’s slug (here default); profiles lists the profiles it adopts by slug.

Governance & permissions

A super admin or Master can manage any contact. Contacts carry Ownership, so a Journey Manager manages the contacts they own.

API access

Contacts have full CRUD through the User API. Public, contact-facing flows — lead capture, registration, and identifier validation — run through the Contact API.

Related

Profiles

The attribute schema a contact adopts.

Organizations

The company or account a contact belongs to.

Segments

Dynamic audiences a contact can fall into.

Document Templates

Structured documents attached to a contact.