Accounts and partners

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.

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"
  }'

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()

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, 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=<account handle>) for the agent that serves the company itself, with the account view.
context(subject=<person handle>, about=<account handle>) for the agent that serves the contact. The pack adds an account block with what the account has that matters to this task.

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",
)

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.

Next steps

Identity and verification

handles, assertions and the V0 to V4 levels.

Context and views

the channel, task and subject views.

Create a link

the request and response in detail.

Patterns

the signals that repeat, with evidence.

Memory basics

What the agent receives

Governance

Accounts and partners

Three kinds of subject

Organization handles

A person and an organization are linked, never merged

Memory stays tied to where it came from

Context by subject

One contact never reads what another said

Patterns at account level

Policy by subject

Erasure

Next steps

Identity and verification

Context and views

Create a link

Patterns

​Three kinds of subject

​Organization handles

​A person and an organization are linked, never merged

​Memory stays tied to where it came from

​Context by subject

​One contact never reads what another said

​Patterns at account level

​Policy by subject

​Erasure

​Next steps

Identity and verification

Context and views

Create a link

Patterns

Three kinds of subject

Organization handles

A person and an organization are linked, never merged

Memory stays tied to where it came from

Context by subject

One contact never reads what another said

Patterns at account level

Policy by subject

Erasure

Next steps