List principal

Returns the caller's org as an economic principal, composed from the apps that own each fact: its legal entity and founders' identity verification (company), the W-9 or W-8 it certified (tax), its wallets (wallet), the agents that answer to it — spawned ones with the agent that spawned them — (agents), its screening against the OFAC, UN, EU and UK sanctions lists and the embargoed jurisdictions, run now, and what it still lacks to pay and be paid.

GET /v1/principal

Principal → · All API references → · Get started →


Address	`https://api.hanzo.ai/v1/principal`
Method	`GET`
Operation	`get_principal`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Any member reads it. The detail behind a verdict — founders' names and statuses, masked tax numbers, treaty claims, sanctions matches — is answered to the org's admins only. An owning app this deployment does not run is named in sources as absent rather than read as empty.

Request

GET /v1/principal takes no parameters and no body — the credential is the whole request.

Response

Status	Body	Meaning
`200`	principal.View	ok
`default`	problem-details	refused

200 body — 87 fields.

Field	In	Type	Always	Description
`agents`	body	principal.AgentBrief[]	—	Agents are the agents that answer to it, spawned ones with their parent.
`agents[].id`	body	string	—	ID is the agent id — the ref a run names and the value a member id derives from, so it must be stable across a reconcile.
`agents[].name`	body	string	—	Name is the display name a person reads in a member list.
`agents[].parent`	body	string	—	Parent is the agent that spawned this one; empty for an agent a person defined.
`agents[].status`	body	string	—	Status is the registry status VERBATIM, never a boolean.
`compliance`	body	principal.Summary	—
`compliance.missing`	body	principal.Step[]	—	Missing are the steps it owes, each with the rule that asks for it.
`compliance.missing[].code`	body	string	—	Code is the step's stable name, for a caller that branches on it.
`compliance.missing[].rule`	body	principal.Rule	—
`compliance.missing[].rule.code`	body	string	—	Code is the rule's stable name, for a caller that branches on it.
`compliance.missing[].rule.reason`	body	string	—	Reason is the rule, stated.
`compliance.missing[].what`	body	string	—	What must happen, in words.
`compliance.missing[].where`	body	string	—	Where it is done, when it is done on this platform.
`compliance.missing[].who`	body	string	—	Who does it: payer, payee, or "Hanzo platform reviewer".
`compliance.ready`	body	boolean	—	Ready is true when it lacks nothing its own facts decide.
`entity`	body	principal.Entity	—
`entity.ein`	body	string	—	EIN is on_file when the org's W-9 carries an EIN, and absent otherwise.
`entity.founders`	body	principal.Founder[]	—	Founders are its beneficial owners with their verification status — answered to the org's admins.
`entity.founders[].equityBps`	body	integer (int64)	—	EquityBps is ownership in basis points, 0–10000.
`entity.founders[].kyc`	body	string	—	KYC is pending, verified, reviewer_confirmed or failed, verbatim.
`entity.founders[].name`	body	string	—	Name is the full legal name.
`entity.imported`	body	boolean	—	Imported is an entity that existed before and was imported.
`entity.jurisdiction`	body	string	—	Jurisdiction is the U.S. state of formation.
`entity.name`	body	string	—	Name is the company name.
`entity.stage`	body	string	—	Stage is the formation's stage; "company" is formed.
`entity.structure`	body	string	—	Structure is c-corp, llc or dao-llc.
`identity`	body	principal.Identity	—
`identity.reason`	body	string	—	Reason says which founders, and what is outstanding.
`identity.status`	body	string	—	Status is verified (every founder of its formation passed identity verification through the licensed provider, or a platform reviewer confirmed them), pending, failed, or none (no formation, or one naming no founder).
`org`	body	string	—	Org is the org — the principal itself.
`sanctions`	body	principal.Screening	—
`sanctions.at`	body	integer (int64)	—	At is when it ran, unix seconds.
`sanctions.lists`	body	principal.List[]	—	Lists is each publisher's readiness at the moment of screening.
`sanctions.lists[].attempted_at`	body	string (date-time)	—	AttemptedAt is when the last attempt happened, successful or not.
`sanctions.lists[].designations`	body	integer (int64)	—	Designations is how many entries the last successful load carried.
`sanctions.lists[].digest`	body	string	—	Digest is the digest of the payload that produced Designations.
`sanctions.lists[].error`	body	string	—	Err is why the last attempt failed, empty if it succeeded.
`sanctions.lists[].loaded_at`	body	string (date-time)	—	LoadedAt is when that load happened.
`sanctions.lists[].source`	body	string	—	Source is the publisher.
`sanctions.matches`	body	principal.Match[]	—	Matches are what matched — answered to the org's own admins and to a reviewer, never to another org.
`sanctions.matches[].decidedAt`	body	integer (int64)	—	DecidedAt is when, unix seconds.
`sanctions.matches[].decidedBy`	body	string	—	DecidedBy is the reviewer, or "exact designated address".
`sanctions.matches[].entry`	body	string	—	Entry is the designated subject's primary name, or the jurisdiction's.
`sanctions.matches[].foundAt`	body	integer (int64)	—	FoundAt is when a screening first found it, unix seconds.
`sanctions.matches[].hits`	body	principal.Hit[]	—	Hits are the org's names, addresses and countries that matched, in the order they were first seen.
`sanctions.matches[].hits[].kind`	body	string	—	Kind is name (matched fuzzily), address (matched exactly) or jurisdiction.
`sanctions.matches[].hits[].role`	body	string	—	Role is where it came from: entity, founder, form, wallet, or — for a country — citizenship, organization or residence.
`sanctions.matches[].hits[].subject`	body	string	—	Subject is the name, address or country as the org stated it.
`sanctions.matches[].id`	body	string	—	ID addresses the match for a reviewer's decision.
`sanctions.matches[].list`	body	string	—	List is the publisher — ofac, un, eu or ofsi — or jurisdiction for an embargoed place.
`sanctions.matches[].note`	body	string	—	Note is the reviewer's reason.
`sanctions.matches[].org`	body	string	—	Org is the org the match names.
`sanctions.matches[].reason`	body	string	—	Reason is what first matched, and which identifiers agreed or conflicted.
`sanctions.matches[].ref`	body	string	—	Ref is the entry's reference on that list, or the country code.
`sanctions.matches[].score`	body	number (double)	—	Score is the highest similarity seen, 0 to 1; an address or a jurisdiction is 1.
`sanctions.matches[].status`	body	string	—	Status is open (a reviewer decides), cleared (a namesake, decided) or confirmed (the designated person, decided — or a designated address).
`sanctions.reason`	body	string	—	Reason says why, in words.
`sanctions.status`	body	string	—	Status is clear, review (a possible match awaits a platform reviewer), blocked (a confirmed match), unscreened (the org states nothing to screen), or unavailable (the lists are not fit to screen against).
`sources`	body	principal.Source[]	—	Sources says which owning apps answered.
`sources[].app`	body	string	—	App names it: company, tax, wallet or agent.
`sources[].status`	body	string	—	Status is read, or absent when this deployment does not run it.
`tax`	body	principal.Form	—
`tax.certified`	body	boolean	—	Certified is whether the signature covers the current facts.
`tax.chapter3`	body	string	—	Chapter3 and Chapter4 are a W-8BEN-E's statuses — to the org's admins.
`tax.chapter4`	body	string	—
`tax.country`	body	string	—	Country is US for a W-9, or the country of citizenship or incorporation.
`tax.expires`	body	integer (int64)	—	Expires is when a W-8 stops being valid, unix seconds.
`tax.foreignTin`	body	string	—
`tax.form`	body	string	—	Form is w9, w8ben or w8bene.
`tax.residence`	body	string	—	Residence is the country of the permanent residence address.
`tax.tin`	body	string	—	TIN and ForeignTIN are masked — answered to the org's admins.
`tax.treaty`	body	principal.Treaty	—
`tax.treaty.article`	body	string	—	Article is the treaty article and paragraph claimed, e.g. "12(2)".
`tax.treaty.conditions`	body	string	—	Conditions is the explanation the form asks for: the conditions of the article the beneficial owner meets.
`tax.treaty.country`	body	string	—	Country is the treaty country the beneficial owner is resident in.
`tax.treaty.income`	body	string	—	Income is the type of income the claim covers: services, rents, royalties or other.
`tax.treaty.lob`	body	string	—	LOB is W-8BEN-E line 14b: the treaty's limitation on benefits provision the entity meets.
`tax.treaty.rateBps`	body	integer (int64)	—	RateBps is the claimed withholding rate in basis points: 0 is exempt, 1000 is 10%.
`tax.usPerson`	body	boolean	—	USPerson is true for a W-9.
`tax.valid`	body	boolean	—	Valid is whether it establishes what it certifies today.
`wallets`	body	principal.WalletBrief[]	—	Wallets are its addresses.
`wallets[].address`	body	string	—
`wallets[].agent`	body	string	—	Agent is the agent the wallet is scoped to, when it is one agent's.
`wallets[].chain`	body	string	—
`wallets[].custody`	body	string	—
`wallets[].id`	body	string	—
`wallets[].name`	body	string	—

Failure carries the platform error shape — see Errors.

Examples

hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.

import { Configuration, PrincipalApi } from 'hanzoai';

const api = new PrincipalApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getPrincipal();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import PrincipalApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = PrincipalApi(client).get_principal()

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.PrincipalAPI.GetPrincipal(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, principal_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = principal_api::get_principal(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.PrincipalApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new PrincipalApi(client).getPrincipal();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl https://api.hanzo.ai/v1/principal \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP declares no tool for principal — tools/list on https://api.hanzo.ai/v1/mcp names the products it does reach. Use HTTP or an SDK.

Principal API · All Hanzo APIs · Interactive reference

Request

Response

Examples

On this page