Identity and verification

Niadra recognizes the same customer on WhatsApp, on the phone, in your app and in your CRM. It does so without guessing: every link between two identifiers is a recorded assertion, with a method and evidence, and every link can be undone. This page covers handles, profiles, assertions and the verification levels that decide what each conversation may read.

Handles

A handle is an identifier of a subject in some channel or system. It has a type, a value and, when the type needs one, a scope:

`type`	What it is	`scope`
`phone_e164`	A phone number in E.164, such as `+14155550123`
`wa_id`, `wa_jid`, `wa_lid`	Identifiers WhatsApp delivers
`wa_bsuid`	A WhatsApp user id scoped to one business account	The WhatsApp Business account
`email`	An e-mail address, lowercased
`gov_id_hmac`	An HMAC of a national ID number, never the number in clear	The country
`app_user_id`	The user id in your app or site
`system_id`	The id of the subject in a system of record	The system, such as `crm`
`org_registry_hmac`	An HMAC of a company registry number	The country
`email_domain`	An organization’s e-mail domain, only as a hint
`anon_id`	A visitor or device not yet identified

Values are classified by their format, never by the name of the field they came from, and normalized on the server. The SDKs have helpers that build each type:

from niadra import phone, email, whatsapp, whatsapp_bsuid, system_id, app_user, anonymous

phone("+1 415 555 0123")          # phone_e164: +14155550123
system_id("crm", "48213")         # system_id in the crm namespace
whatsapp_bsuid("US.1a2b3c", "waba-771")

import { handles } from "@niadra/sdk";

handles.phone("+14155550123");
handles.systemId("48213", "crm");
handles.waBsuid("US.1a2b3c", "waba-771");

Every handle belongs to a kind of subject, in subject_kind: person (the default), account or partner. org_registry_hmac and email_domain are organization handles from the start. See Accounts and partners.

Profiles and assertions

A profile is the customer as the memory sees them: the set of handles linked to one another. Each link is an assertion in an immutable log, with the method that produced it:

Method	When it happens
`explicit_identify`	You stated it, through `identify()`
`otp`, `login`	The customer proved possession of the handle
`system_import`	Initial load from your CRM or a file
`same_event`	Two strong handles arrived in the same event, such as phone and `wa_id`
`external_resolver`	Your own identity system resolved it and sent the result
`declared`	The customer said so; weak until confirmed

When two handles in one event resolve to different profiles, the merge happens outside the batch answer, under a lease. Memory stays attached to the handle each fact came from, so splitting two profiles merged by mistake is a real operation: facts, orders and invoices go back to the right owner on their own.

niadra.identify(
    [phone("+14155550123"), system_id("crm", "48213")],
    method="system_import",
)

await niadra.identify({
  handles: [handles.phone("+14155550123"), handles.systemId("48213", "crm")],
  method: "system_import",
});

curl -X POST "https://acme-prod.us-east-1.api.niadra.com/v1/batch" \
  -H "Authorization: Bearer $NIADRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"type": "identify", "idempotency_key": "idf-48213", "method": "system_import",
       "handles": [{"type": "phone_e164", "value": "+14155550123"}, {"type": "system_id", "value": "48213", "scope": "crm"}],
       "occurred_at": "2026-09-22T17:00:00Z"}]}'

identify() is sent right away, outside the queue, so the next context() already sees the merged profile.

Safeguards against wrong merges

Two profiles that already hold a handle at V3 or above are never merged automatically; only by a forced merge, with actor and reason.
Test values and QA placeholders are blocked per type, from a fixed list you can extend.
Each profile has per-type limits: one national ID per country, one system_id per namespace, a few phones. Past the limit, the weakest handle is demoted, and ingestion is never rejected.
A handle that links many profiles in a short time (a store tablet, a PBX number, a support WhatsApp) becomes ambiguous: usable for reads, never for new merges.
A phone number or BSUID rotation creates an alias, never an automatic merge.
A person and an organization are never merged. A link is what connects them.

An unknown, partial (a BSUID with no phone yet) or ambiguous handle gets a provisional profile and an empty context. When in doubt, the memory reveals nothing.

Governing identity

Your team corrects identity through the governance routes, with a Console person holding the security or integration role, or a source key with the admin scope. Every write requires an Idempotency-Key header, answers 202 with an operation id and is applied under the profile lease, in order:

What	Route
See why two handles are one profile	`GET /v1/identity/assertions`, filtered by `profile_id` and `state` (`applied`, `pending`, `rejected`)
State that handles belong together	`POST /v1/identity/assertions`, with `handles`, `method` and `reason`
Undo one wrong link	`POST /v1/identity/assertions/{assertion_id}/retract`
Force a merge the safeguards refused	`POST /v1/identity/merge`, with `profile_ids`, `force` and `reason`
Split a profile	`POST /v1/identity/unmerge`, with `profile_id` and the `handle_ids` or `assertion_ids` to separate
Stop a value from ever linking profiles	`POST /v1/identity/handles/block`

Niadra also proposes links it cannot prove, such as two profiles with the same name and a similar e-mail. It never applies them on its own: GET /v1/identity/suggestions lists them with a score and the features behind it, accept turns one into an accepted_suggestion assertion, and dismiss closes it. To find a profile from a handle, use POST /v1/profiles/search: the value goes in the body and is never logged. GET /v1/profiles/{profile_id} returns its handles, links, subject kind and pseudonym, masked for the role of whoever reads.

Verification levels

The same customer gets different context depending on how much the conversation proved who they are:

Level	Meaning	Example
`V0`	Self-declared	”This is Marina” in an anonymous chat
`V1`	Plausible by channel	Came from that number, no strong attestation
`V2`	Attested by the channel	A call with network attestation A, an authenticated WhatsApp sender
`V3`	Challenged	OTP on the same channel or a login in your app
`V4`	Documentary or by an attendant	Checked against the system of record or by a person
`no_customer`	A task with no customer present	Internal billing agent

Your policy sets the minimum level per category of memory. The context reports in withheld how many items were held back: the agent knows that verifying releases more, without seeing the content. no_customer sits outside the scale and is only accepted from sources with the internal_agent audience; that context never reaches the end customer.

Effective level

The level that applies is the lowest of three: what you requested, the source ceiling and what the conversation proved. The ceiling is an attribute of the source: automated agents V2, sources that run OTP V3, V4 only for human desks and systems of record. A leaked agent key cannot declare V4. The context response shows both sides in verification: requested, effective and, when effective is lower, reason (source_ceiling or not_proven).

Raising the level

The level goes up through a verify event, never by inference. It applies to that conversation or task, with an optional expiry. After it, request a new context(): the SDK has already dropped the cached context of that conversation.

niadra.verify(
    "otp_whatsapp",
    "V3",
    handle=phone("+14155550123"),
    conversation_id="wa-8812",
)
ctx = niadra.context(subject=phone("+14155550123"), verification="V3", conversation_id="wa-8812")

await niadra.verify({
  handle: handles.phone("+14155550123"),
  method: "otp_whatsapp",
  level: "V3",
  conversation_id: "wa-8812",
});
const ctx = await niadra.context({ subject: handles.phone("+14155550123"), verification: "V3", conversation_id: "wa-8812" });

The methods are otp_whatsapp, otp_sms, login, kba, network_attestation and human_agent. A verify above the source ceiling comes back in the 207 with the code verification_not_allowed. For voice, the network attestation of the call (STIR/SHAKEN and equivalents) maps A to V2, and B and C to V1.

Next steps

Context and views

what each level releases in the context.

Accounts and partners

organizations and role-based links.

List assertions

the API of the identity log.

Identity suggestions

links to review, never applied on their own.

Memory basics

What the agent receives

Governance

Identity and verification

Handles

Profiles and assertions

Safeguards against wrong merges

Governing identity

Verification levels

Effective level

Raising the level

Next steps

Context and views

Accounts and partners

List assertions

Identity suggestions

​Handles

​Profiles and assertions

​Safeguards against wrong merges

​Governing identity

​Verification levels

​Effective level

​Raising the level

​Next steps

Context and views

Accounts and partners

List assertions

Identity suggestions

Handles

Profiles and assertions

Safeguards against wrong merges

Governing identity

Verification levels

Effective level

Raising the level

Next steps