Welcome to the Hira Docs
Verification sessions with hosted applicant walks, a sandbox account beside every live account, signed webhooks and a TypeScript SDK, alongside event monitoring, check and address screening.
Start building →Overview
A customer’s backend calls the /v1 API with an account API key, directly or through @hira/sdk. It creates a verification session for a person or a business, hands the session’s link to that person once, and reads the outcome back through the API or a signed webhook. The person walks the program’s flow on Hira’s hosted page. Every live account has a sandbox account with test keys, where a session’s outcome can be simulated. The same keys also record activity, ask before an action moves, screen an address against the account’s lists and register parties in the directory.
Every live account is born with a sandbox account: the same people, its own data, its own keys. An account holds workspaces, and each program sits in one; a key speaks for the whole account and for one source app. Live keys start hira_sk_live_ and sandbox keys hira_sk_test_, and each reaches only the products in its scopes: Identity verification, Directory, Transaction monitoring. Every refusal answers the error envelope { error, code, param }.
Concepts
The concepts a developer meets in the product as built, in the order the sidebar lists them, and the catalogue of what the product carries.
One walk of a program’s flow through a bearer link that lasts 72 hours unless set. status created to completed, decision approved, declined or in_review, replay-safe creates, simulate in the sandbox.
Five signed session events with a thin body of ids and seq. Verified with constructEvent, answered 2xx within 10 seconds, retried for about 92 hours on a live account.
Users and businesses in the directory, named by the account’s own customerRef; a key writes parties and reads none, and the receipt’s kind is user or business.
One source app and one event type. track() records activity in the background, fail-open, and the subscribed programs judge it on arrival.
Rules with soft and hard limits, each band routed to No action, In review or Decline, which check() answers as Allow, Hold or Deny.
A set of policies over one source: subscribed event streams, or a hosted verification flow that sessions open on.
The case a breach opens, Soft or Hard, with an SLA, and the decisions recorded on it, read as approvals.
Every verification check, event type, policy template and risk indicator the product carries, each with its status: live, or in the product with its engine not live yet.
Get started
Three paths that run against a sandbox account today.
Create a verification session, hand over its link, simulate the walk in the sandbox and read the decision. Live sessions open once an engine is connected.
Quickstart → Screen a counterpartyCheck one address against the lists the account maintains. No external sanctions source is connected yet.
API reference → Monitor transactionsRecord movements with track() and let a program’s policies judge them: value thresholds and velocity; structuring by counterparty runs on chain transfers.
Guides
By business type: what the policies and doors built today cover for each. No guide page is written yet; each card points at the reference that holds the pieces.
Judge each payout against the account’s own lists, an allowlist, value thresholds and velocity, and ask before it moves with check(). Settlement matching and payer-data checks are not in this build.
Watch outflows with value thresholds, velocity per wallet and, on chain transfers, structuring by counterparty. Grouping across a customer’s accounts is not in this build.
Policies → Stablecoin issuersCheck every mint and burn against the approved-minters list, compare reserves with circulating supply on each reserve.snapshot, and match onchain mints to recorded ones by txHash. Redemption checks are not in this build.
Not in this build: screening is one address per call, and nothing models float or what is owed to sellers.
Not in this build Tokenization & RWAMatch onchain mints to recorded ones and hold an asset-concentration limit on monitored holdings. Instruction matching beyond mints is not in this build.
Policies → Custodians & treasuryRaise a case on each pause, blacklist, upgrade, role grant or mint-authority change recorded through admin.action, and hold an asset-concentration limit. Balance caps and chain or protocol concentration are not in this build.
Customers
The party behind the activity: registered in the directory, verified through a hosted walk, judged by the account’s policies.
Register users and businesses in the directory, record beneficial owners and directors, and run a person or a business through a hosted verification session. Sessions run in the sandbox today; authority to act is not in this build.
Identity → Screen against listsMatch addresses on every event against the lists the account maintains, and screen one address on request. PEP checks and external sanctions sources are not in this build.
Screening → Monitor behaviourVelocity in and out, large inflows and new counterparties, judged per wallet. Grouping by party is not in this build.
Policies → Rate customer riskAn analyst states the customer risk rating, low, medium or high, when resolving a verification case, and the session answers it as riskRating. An automatic rating is not in this build.
Payments
Money sent on a customer’s behalf, judged by the program’s policies before or after it moves.
Match each payout’s counterparty against the account’s own lists, one payout at a time, and ask before it moves with check(). Batch runs and external sanctions sources are not in this build.
A value limit on one movement, and a count or sum over a trailing window, each with a soft and a hard limit.
Policies → Reconcile settlementNot in this build: nothing matches a payment instruction to its settlement.
Not in this build Catch missing payer dataNot in this build: the originator and beneficiary checks are drafts, and no policy reads beneficiaryInfo.
Treasury
The platform’s own wallets, keys and holdings.
Each pause, blacklist, upgrade, role grant or mint-authority change sent as admin.action raises a case that runs on the program’s SLA clock.
One asset’s share of monitored holdings, checked continuously. Hot-wallet ceilings and concentration by wallet, chain, issuer or protocol are not in this build.
Policies → Reconcile float vs obligationsNot in this build: nothing models what is owed against the balance held.
Not in this buildIssuance
The supply itself: tokens minted and burned, and the reserves behind them.
Each mint and burn checked against the approved-minters list, and each onchain Ethereum mint matched by txHash to a recorded mint on a sweep. Redemptions are not matched to an authorization.
Circulating supply against reserves on every reserve.snapshot, with a soft and a hard ratio. The movements behind it are recorded and not yet judged.
Not in this build: no policy matches a redemption to the burn that settled it.
Not in this buildA sandbox account beside every live account
Every live account is born with a sandbox account named after it with “· Sandbox” on the end: the same people, its own data, its own consent settings and test keys starting hira_sk_test_. Its plan, seats and status follow the live account. Administration › Developer › Sandbox › Open sandbox switches to it, and its API keys are created there under Developer › API keys.
In the sandbox, simulate concludes an open verification session with the outcome asked for, through the same recorder and policies as a real walk, marked simulated. A sandbox account creates up to 500 sessions per UTC day, and its webhook deliveries are tried three times within an hour. On a live key today, creating a session answers 403 engine_not_connected and simulate answers 400 simulate_not_allowed.
await hira.verificationSessions.simulate(id, { outcome: "verified" }); await hira.verificationSessions.simulate(id, { outcome: "failed" }); await hira.verificationSessions.simulate(id, { outcome: "unable-to-verify" }); // every remaining step concludes with that outcome, assurance "simulated"; // the decision is what the program's policies make of it // or preset at create, and the hosted page opens on it: await hira.verificationSessions.create({ programId, customerRef, simulate: { outcome: "failed" } }); // on a live key create // → 403 engine_not_connected simulate // → 400 simulate_not_allowed