Identity

An address is not a person. A party is the customer or business behind the addresses and references that appear across events and sessions. The console lists parties under Users and Businesses, and each party’s record has the tabs Overview, Profile, Verification, Documents, Screening, Exceptions and Activity, with Ownership on a business, Connections on a person, Wallets when the party holds wallets, and Transactions when it holds wallets or a reference.

Identifiers

A party carries identifiers: onchain addresses, the account’s own customer reference (customerRef), and service and device ids. Each identifier value has one owning party per account. A party’s profile holds the details given at onboarding: a date of birth, or a registration number and incorporation country, with contact details and an address. A case records the party its event named when it is raised, so the party’s Exceptions tab lists every case about it.

A customerRef is the account’s own opaque id: 1 to 120 letters, digits and . _ : / -, case-sensitive. A value containing @ or starting with + is refused as an email address or a phone number. The same reference names the party on a directory create, on a verification session and in an event’s fromPartyRef or toPartyRef.

Canonical form

Addresses are stored in a single form: 0x addresses lowercased at write, base58 kept exactly as sent. Database constraints hold the form on wallets, wallet history, chain transfers, recorded events and screening list entries.

Directory

A key with the Directory scope registers parties: POST /v1/directory/users and POST /v1/directory/businesses. A key writes parties and reads none: every success answers a receipt of four fields, and no stored field of the party comes back.

const user = await hira.directory.users.create({
  displayName: "Sana Ahmed",
  customerRef: "crm-1042",          // the idempotency key
  dateOfBirth: "1993-04-11",
});
// { id: "…", kind: "user", customerRef: "crm-1042", created: true }

const business = await hira.directory.businesses.create({
  legalName: "Acme Pty Ltd",
  customerRef: "crm-8801",
  registrationNumber: "ACN 000 111 222",
  incorporationCountry: "Australia",
});

A customerRef that already names a party of the same kind writes nothing and answers the same id with created: false; one that names a party of the other kind answers 409 party_kind_mismatch. A field the door does not declare answers 400 unknown_field. The API reference lists every field.

Ownership

A business records its beneficial owners and directors as dated relationships on the record’s Ownership tab. Closing one ends it rather than rewriting it, so ownership can be read as at a date. These are recorded in the console; the API has no door for them.

Verification

A person or a business is verified by walking a program’s flow on Hira’s hosted page, through a link from a verification session. A session’s customerRef names the party: a party of the flow’s kind is reused, else one is registered. The session answers its partyId, and the party’s Verification tab shows the walk.

Sessions run in the sandbox today: a live key answers 403 engine_not_connected. A sandbox result is simulated, and the party’s record counts a simulated result beside its verified figure, never in it. See the quickstart.