Core Concepts

Status: Draft Last Updated: 2026-06-15 Audience: customer

Unbound gives you a single, normalized view of each end user’s data across the platforms they use. Whatever you integrate with — an assistant, a dashboard, a timeline — you query the same six entities regardless of which source the data originally came from. This page explains what those entities mean, how they relate, and the two ideas that make a cross-platform view possible: the two-tier identity model and grants.

All example values here are synthetic (e.g. @example.test). Replace them with your own.

The shape of the data

An end user’s life, as Unbound models it, comes down to six entity types:

Entity	What it represents
Person	One real human, unified across every platform they appear on.
PlatformIdentity	How a person appears on one specific platform — a phone number, an email address, a handle.
Conversation	A context where messages are exchanged: a DM, a group chat, an email thread, a channel.
Message	A single unit of communication within a conversation.
Event	A named block of time — a meeting, a birthday, a deadline, an all-day event.
Document	Authored content where the value is what it says: a note, a file, a journal entry.

Everything you query through the Data API is one of these. They are platform-agnostic: an iMessage, a Gmail message, and an Android SMS are all just Messages, and you filter by source only when you want to.

People and platform identities

The hardest part of unifying personal data is that the same human shows up everywhere under a different name. Unbound handles this with two tiers of identity.

PlatformIdentity — the raw, per-platform identity

A PlatformIdentity is how someone appears on one platform: +15555550142 in iMessage, dana@example.test in Gmail, a Slack-style handle in a workspace. It is the literal identifier the source reported, along with whatever profile detail that platform carries (display name, avatar). A platform identity always exists on its own — even before Unbound knows who it belongs to.

Person — the canonical, cross-platform identity

A Person is one real human. It sits above platform identities: many PlatformIdentities can resolve to a single Person. When you query a Person, you get a unified view of that human across every platform they appear on — all of “Dana’s” messages, no matter which source each one came from.

PlatformIdentity ──┐
PlatformIdentity ──┼──▶ Person   ("Dana")
PlatformIdentity ──┘

This is why a Person carries a list of the platforms they appear in, and why a Message’s sender can be either a resolved Person or a still-unresolved PlatformIdentity — see how this surfaces when you query in the Data API.

Entity resolution (linking identities)

The process of recognizing that several platform identities are the same human is called entity resolution. Two things about it matter when you build on Unbound:

It is asynchronous, and it never blocks your data. New data is queryable the moment it lands, attached to its platform identity. Resolution runs in the background and improves the view over time — a Person query that returns only Gmail messages today may start including iMessage conversations once those identities link up. You never wait on resolution to read data.
The link improves, it doesn’t rewrite. Resolution links platform identities to a Person; it never edits the underlying messages, events, or documents. “Dana’s messages” simply means “messages from every platform identity currently linked to Dana.” Because nothing is mutated, links can be adjusted (merged, split) and your query results follow along automatically.

The practical takeaway: an unresolved identity is normal and temporary, not an error. If a Person looks like it is missing data you expect, that data is still there under a not-yet-linked platform identity — it will fold in as resolution catches up.

Conversations and messages

A Conversation is any context in which messages are exchanged — a 1:1 DM, a group chat, an email thread, a channel. Conversations can nest: a channel is a conversation, and a thread inside it is a child conversation, to any depth. Each conversation belongs to a single platform and has participants (Persons), and that participant list is temporal — people join and leave over time, and that history is preserved.

A Message is one unit of communication inside exactly one conversation. Each message has:

A sender — one Person (or a PlatformIdentity, if not yet resolved).
Recipients — zero or more Persons, each with an optional role (to, cc, bcc, mention). Recipients capture who a message was actually directed at, which can differ from the conversation’s full participant list.
Content — a text body plus zero or more attachments. Content isn’t only text: a message can be media, a call (with duration and optionally a transcript), or a system event (“participant joined”).

Attachments are queryable in their own right, so “every image shared in this conversation” is a natural query, not a manual scan of message bodies.

Events

An Event is a named block of time — a meeting, a birthday, a holiday, a deadline, a reminder. An event has a start time and optionally an end time (or an all-day flag), may have participants with roles (organizer, attendee) and response status (accepted, declined, tentative), and may recur.

An event is a commitment of time, not an exchange between people. A calendar invite emailed between two people is a Message that references an Event; the Event itself is the distinct thing that lives on the calendar.

Documents

A Document is content-centric: a note, an uploaded file, a journal entry — anything where the value is what it says, not who sent it to whom. That focus is what separates a Document from a Message (where the exchange is the point). A document may have an author, multiple collaborators, or unknown provenance; it may be owned, shared, or ambiguous; and where the source supports it, revisions are preserved. The content is kept faithfully as the source provided it.

How entities relate

Putting it together:

A Person is the canonical identity that one or more PlatformIdentities resolve to.
A Message belongs to exactly one Conversation, has one sender and zero-or-more recipients (all Persons or PlatformIdentities), and carries its own attachments.
A Conversation has temporal participants and can nest inside a parent conversation.
An Event has optional participants with roles and status.
A Document stands largely on its own, optionally with an author.

Entities can also reference each other across types — a Message can reference the Event it’s about, a Document can reference the Conversation it summarizes. Every such relationship carries provenance: whether it’s a fact the platform reported directly, or something inferred by analysis. The same fact-vs-inference distinction applies to identity resolution itself. Provenance lets you decide what to trust — treat platform-reported and user-confirmed links as solid, and surface inferred ones for confirmation if you choose.

Grants: a source becomes available once the user connects it

You never query “all of Unbound’s data.” You query one end user’s data, and only the sources that user has actively granted. A grant is the end user’s consent to a single source (Gmail, iMessage, and so on); it is created when they connect that source and disappears when they revoke it.

This has direct consequences for how you read data:

Ask what’s granted first. Before querying entities, check which sources are active for the user. A source the user has not granted is simply invisible — its absence looks exactly like having no data, never an error.
Connection is the gate, not configuration. A source only produces entities once the user grants it. New grants make new data appear; revoked grants make it stop.
Some sources arrive late. Granting a source starts an import, but the first batch of data can land minutes — sometimes hours — after the user finishes the flow. An empty result right after a grant often just means the import hasn’t completed yet.

For which sources exist, what each provides, and how long the first import takes, see Data Sources. For how a user is sent through consent and how grants are produced, see Authorization Flow.

Putting it to work

When you query an end user’s data, hold these in mind:

You query six entity types, not platforms — filter by source only when you want to narrow.
A sender or recipient may be a Person or a PlatformIdentity — handle both; the PlatformIdentity case just means resolution hasn’t linked it yet.
Empty results are normal and ambiguous — they can mean “not granted,” “no data,” or “import still in flight.” Check grants to tell them apart.
The view gets richer over time as resolution links identities and asynchronous imports land.

Data API — How to query these entities, filter by source, and read the fields described here.
Data Sources — Which sources exist, what each provides, and how fast its data lands.
Authorization Flow — How an end user grants a source and how grants are produced.