> ## Documentation Index
> Fetch the complete documentation index at: https://docs.niadra.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Accounts and partners
> Organizations as memory subjects, role-based links, and context with about.
In logistics, insurance, healthcare and B2B in general, the customer is often a company, and the person on the line acts on its behalf: the carrier's driver, the retail chain's buyer, the broker. Other organizations take part in service without being customers at all: the carrier that delivers, the clinic that treats, the repair shop that fixes. Niadra keeps memory for all of them. A subject of the memory is a person, an account or a partner.
## Three kinds of subject
| Kind | What it is | Example |
| --------- | ------------------------------------------------------------------------------ | ---------------------------------------------- |
| `person` | A human being, identified by phone, e-mail, WhatsApp id, app id or a system id | Marina Souza |
| `account` | An organization that is your customer | The retail chain behind CRM account `ACC-2201` |
| `partner` | An organization that takes part in service without being a customer | The carrier, the clinic, the insurance broker |
The kind comes from the handles, never from a separate parameter. Every handle carries a `subject_kind`, which defaults to `person` except for organization-only handle types.
## Organization handles
| Handle type | Strength | Notes |
| ----------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `org_registry_hmac` | Strong | The company registry number in its country, sent as an HMAC with your secret, like a personal document number |
| `system_id` with `subject_kind: account` or `partner` | Strong within its namespace | The account in your CRM, the customer code in your ERP, the carrier id in your TMS |
| `email_domain` | Weak hint | Never merges anything on its own; webmail domains are blocked |
| Company phone | Ambiguous by default | A switchboard connects many people to one number |
Organizations never merge automatically and are never deduplicated by name similarity. Only ids link them. One parent level is supported: subsidiaries become sibling accounts under the same `parent_org`.
## A person and an organization are linked, never merged
An assertion between a person handle and an organization handle is refused. What connects them is a **link**, with a role (`buyer`, `technical_contact`, `driver`, `broker`), a validity period, an origin and a confidence. One person can hold several links at once: a driver who works for three carriers has three links.
Links come from four methods: `system_import` (a CRM contact record), `co_occurrence` (an event that carries both ids), `declared` ("I am calling on behalf of carrier X", weak until confirmed) and `login` (a B2B portal). An event with `subjects[]` naming a person and an organization produces a link, never an identity merge.
```bash cURL theme={null}
curl -X POST "https://acme-prod.us-east-1.api.niadra.com/v1/identity/links" \
-H "Authorization: Bearer $NIADRA_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"person": {"type": "phone_e164", "value": "+14155550123"},
"organization": {"type": "system_id", "value": "ACC-2201", "scope": "crm", "subject_kind": "account"},
"role": "buyer",
"can_see_contacts": true,
"method": "system_import"
}'
```
```python Python theme={null}
import os
import uuid
import httpx
response = httpx.post(
"https://acme-prod.us-east-1.api.niadra.com/v1/identity/links",
headers={"Authorization": f"Bearer {os.environ['NIADRA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person": {"type": "phone_e164", "value": "+14155550123"},
"organization": {"type": "system_id", "value": "ACC-2201", "scope": "crm", "subject_kind": "account"},
"role": "buyer",
"can_see_contacts": True,
"method": "system_import",
},
)
response.raise_for_status()
```
```typescript TypeScript theme={null}
const response = await fetch("https://acme-prod.us-east-1.api.niadra.com/v1/identity/links", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.NIADRA_API_KEY}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
person: { type: "phone_e164", value: "+14155550123" },
organization: { type: "system_id", value: "ACC-2201", scope: "crm", subject_kind: "account" },
role: "buyer",
can_see_contacts: true,
method: "system_import",
}),
});
```
Link routes are governance routes: a Console person with the `security` or `integration` role, or a key with the `admin` scope, and an `Idempotency-Key` header. A link takes `role`, an optional `valid_from` and `valid_to`, and `can_see_contacts`, which decides whether this person may read what other contacts of the organization said. When the contact leaves the company, [end the link](/en/api/identity-link-end), optionally with the `valid_to` date. Past conversations keep what they were about; new reads with `about` for that pair answer 422 `about_without_link`.
## Memory stays tied to where it came from
A conversation between Marina and your agent about the retail chain becomes an episode whose subject is Marina and whose `about` is the account. Business objects belong to the handle that owns them: an order placed by the retail chain lives on the account, and Marina is connected to it through her link. Because every item points back to its origin, an unmerge or an erasure lands on the right subject without rewriting anything.
## Context by subject
Two calls cover the two situations:
* `context(subject=)` for the agent that serves the company itself, with the `account` view.
* `context(subject=, about=)` for the agent that serves the contact. The pack adds an account block with what the account has that matters to this task.
```python Python theme={null}
from niadra import Niadra, phone, system_id
niadra = Niadra()
ctx = niadra.context(
subject=phone("+14155550123"),
about=system_id("crm", "ACC-2201", kind="account"),
view="chat",
verification="V1",
conversation_id="wa-8812",
)
```
```typescript TypeScript theme={null}
import { Niadra, handles } from "@niadra/sdk";
const niadra = new Niadra();
const ctx = await niadra.context({
subject: handles.phone("+14155550123"),
about: handles.systemId("ACC-2201", "crm", { subjectKind: "account" }),
view: "chat",
verification: "V1",
conversation_id: "wa-8812",
});
```
`about` needs an active link between the two subjects. Without one, the answer is 422 `about_without_link`, and it never reveals whether the organization exists.
The `account` view gathers the account facts (contract, SLA, terms), open items and promises at account level, open business objects, recent episodes with any contact (with the contact's name and role), account patterns and the actions internal agents took on the account. Up to 20 contacts are listed in detail, plus a count of the others. The `partner` view works the same way for partners.
### One contact never reads what another said
Personal data of a contact is still personal data in B2B, and GDPR and LGPD make no exception for it. For links without `can_see_contacts` (the driver, the technical contact), what other contacts said appears only as a count and a topic. Names and content reach only links that carry it, such as the buyer or the account manager. The role of the link is also a context attribute of the policy.
### Patterns at account level
An account pattern such as `recurring_complaint` can add up complaints from several contacts. It only counts evidence the `account` view audience may read, inherits the most restrictive category among its evidence, and needs at least two different contacts.
## Policy by subject
Audience classes include the subject kind. An agent that calls carriers sees `partner` context, not `account` context. The `partnership` and `logistics` purposes exist in the catalog, and by default a vendor never sees the context of a partner that competes with it.
## Erasure
Forgetting a person does not erase the account. It removes the person's own memory, including what they said about the account, and ends their links. What the account knows from system events or from other contacts stays. Forgetting an account erases the account facts, objects and patterns and ends its links, without touching each contact's personal memory, which only goes when the data subject asks. Both paths issue a receipt. See [Privacy, erasure and export](/en/concepts/privacy).
## Next steps
handles, assertions and the V0 to V4 levels.
the channel, task and subject views.
the request and response in detail.
the signals that repeat, with evidence.