> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unpod.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Entities

> System-of-record identity - one person, one history, across every channel.

An entity is system-of-record identity: a call, a WhatsApp reply, and an
email from the same person are one entity with one history - not three
records in three systems.

Every channel API hands you a different handle for the same human: a phone
number on the call, a WhatsApp ID on the message, an address on the email.
Without a shared identity layer, your agent treats each as a stranger and
your data splits three ways. Entities collapse those handles into one
record, so every touch on every channel resolves to the same person before
your agent sees it. Today that works for phone numbers; cross-channel
resolution is in build.

People and organizations are both first-class. In an enterprise sale the
customer is the company - individual contacts roll up to it. In a consumer
sale the customer is the person. Your CRM stays where it is; the entity
table is the working copy your agents read and write in real time.

Upsert a person once with their known identities, and every future
interaction on any of those channels resolves to them. This is the shape
the unified SDK will take:

```python Illustrative - not callable today theme={null}
entity = unpod.entities.upsert(
    name="Priya Sharma",
    identities=[
        {"channel": "phone", "value": "+91981..."},
        {"channel": "whatsapp", "value": "+91981..."},
        {"channel": "email", "value": "priya@acme.com"},
    ],
)
```

Today this lives in [People in the Platform](https://docs.unpod.ai/platform/space-view/people.md)
and the [Space APIs](https://docs.unpod.ai/api/space/organizations.md).

## The primitives

| Primitive | What it is | Where it lives today |
| - | - | - |
| People | A human the system knows - the record every channel resolves to | [People](https://docs.unpod.ai/platform/space-view/people.md) - production |
| Organizations | A company as a first-class customer; contacts roll up to it | [Organizations API](https://docs.unpod.ai/api/space/organizations.md) - in build |
| Identities | Channel handles (phone, WhatsApp, email) attached to a person | Phone identity on [People](https://docs.unpod.ai/platform/space-view/people.md) - production. Cross-channel identities and merge - in build |

## On the spine

Entities are where the spine starts: channels deliver every inbound touch
to an entity, and every [conversation](https://docs.unpod.ai/context/conversations.md) belongs
to one. Entities read identity handles from channel payloads, write the
resolved person or organization record, and emit entity created, updated,
and merged events. The [Context Engine](https://docs.unpod.ai/context/overview.md) hangs
facts and history off the entity record.

## What stays hidden

Matching and dedup. As cross-channel resolution ships, how a raw phone
number or email is normalized, scored, and merged into an existing record
stays Unpod's job: you upsert identities and read one record. The
resolution machinery is not a public surface.

## Status

People with a phone identity: production. Cross-channel identity
resolution and merge: in build. Companies (organizations): in build.

## Go deeper

> [card] [People](https://docs.unpod.ai/platform/space-view/people.md)
>
> Manage people and their channel identities in the Platform today.

> [card] [Organizations API](https://docs.unpod.ai/api/space/organizations.md)
>
> Company records and rollup via the Space APIs.

> [card] [Conversations](https://docs.unpod.ai/context/conversations.md)
>
> The channel-neutral threads every entity's touches belong to.

> [card] [Context Engine](https://docs.unpod.ai/context/overview.md)
>
> Persistent memory attached to each entity.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.