Replace structure

Records the entity kind, the state of formation and the proposed name.

PUT /v1/company/structure

Company → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/company/structure`
Method	`PUT`
Operation	`put_company_structure`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Records the entity kind, the state of formation and the proposed name. Available only at the structure stage; an unknown structure or jurisdiction, or an empty name, is refused with 400.

Request

3 fields, body application/json (required).

Field	In	Type	Required	Description
`jurisdiction`	body	string	—	Jurisdiction is the state of formation: DE or WY.
`name`	body	string	—	Name is the proposed company name.
`structure`	body	string	—	Structure is the legal entity: c-corp, llc or dao-llc.

Response

Status	Body	Meaning
`200`	company.formationView	ok
`default`	problem-details	refused

200 body — 39 fields.

Field	In	Type	Always	Description
`formation`	body	company.Formation	—
`formation.alreadyIncorporated`	body	boolean	—	AlreadyIncorporated declares an org that already has a legal entity, which takes the import path (structure → import → company) instead of forming one.
`formation.capTableImported`	body	boolean	—	CapTableImported reports whether the existing company's cap table has been imported onto the canonical cap table.
`formation.createdAt`	body	integer (int64)	—	CreatedAt is the unix second the formation was opened.
`formation.documentIds`	body	string[]	—	DocumentIDs are the data room ids of the GENERATED formation documents.
`formation.esignRef`	body	string	—	EsignRef is the e-signature provider's reference for the signature request.
`formation.filing`	body	company.Filing	—
`formation.filing.at`	body	integer (int64)	—	At is the unix second the filing record was written.
`formation.filing.note`	body	string	—	Note explains a filing Hanzo did not perform itself: what remains to be done and by whom.
`formation.filing.provider`	body	string	—	Provider is the filing partner that performed the filing, or "manual" when no partner is wired.
`formation.filing.ref`	body	string	—	Ref is the partner's or the state's filing reference.
`formation.filing.status`	body	string	—	Status is manual (no partner wired — a registered agent files out-of-band), submitted (the partner accepted it, awaiting the state), filed (the state accepted it) or rejected.
`formation.founders`	body	company.Founder[]	—	Founders is every founding stakeholder, with its equity split and KYC state.
`formation.founders[].decidedBy`	body	string	—	DecidedBy is who settled a terminal KYC status: the provider name, or a reviewer's user id.
`formation.founders[].email`	body	string	—	Email is the founder's email, and the key a KYC decision addresses a founder by — POST /v1/company/kyc/decision matches on it.
`formation.founders[].equityBps`	body	integer (int64)	—	EquityBps is the founder's ownership in basis points, 0–10000 (1% == 100 bps, so 10000 is the whole company).
`formation.founders[].kycRef`	body	string	—	KYCRef is the idv provider's session reference for this founder.
`formation.founders[].kycStatus`	body	string	—	KYCStatus is the founder's identity-verification state: pending, verified (a real idv provider reported a pass), reviewer_confirmed (a privileged reviewer confirmed out-of-band) or failed.
`formation.founders[].name`	body	string	—	Name is the founder's full legal name, as it appears on the formation documents.
`formation.genesis`	body	company.Genesis	—
`formation.genesis.at`	body	integer (int64)	—	At is the unix second the genesis root was computed.
`formation.genesis.block`	body	integer (uint64)	—	Block is the L1 block the anchoring transaction landed in.
`formation.genesis.chainId`	body	integer (int64)	—	ChainID is the EVM chain the root is committed to — the Hanzo L1 by default.
`formation.genesis.note`	body	string	—	Note explains an unanchored genesis honestly — anchor wiring absent, or the submit error — rather than reporting a commit that did not happen.
`formation.genesis.root`	body	string	—	Root is the 0x-prefixed keccak256 root of the founding allocation.
`formation.genesis.status`	body	string	—	Status is pending (root computed, not yet on-chain) or anchored (committed).
`formation.genesis.txHash`	body	string	—	TxHash is the L1 transaction hash of the anchoring commit.
`formation.imported`	body	boolean	—	Imported reports whether the existing company's corporate documents have been ingested into the org's data room.
`formation.importedDocs`	body	string[]	—	ImportedDocs are the data room ids of the documents ingested from Drive.
`formation.jurisdiction`	body	string	—	Jurisdiction is the state of formation: DE or WY.
`formation.name`	body	string	—	Name is the company name the entity is being formed under.
`formation.org`	body	string	—	Org is the owning org — the tenant key, and the reason there is exactly one formation per org.
`formation.paid`	body	boolean	—	Paid reports whether the one-time formation fee has been charged.
`formation.paymentRef`	body	string	—	PaymentRef is the billing reference recorded for the charged formation fee on the org's own ledger.
`formation.signed`	body	boolean	—	Signed reports whether the formation documents have come back signed — the e-signature provider's answer, which a real provider's webhook drives.
`formation.stage`	body	string	—	Stage is the machine's current state: structure, founders, payment, documents, esign or genesis on the formation path, import on the skip path, and company at the terminal.
`formation.structure`	body	string	—	Structure is the legal entity being formed: c-corp, llc or dao-llc.
`formation.updatedAt`	body	integer (int64)	—	UpdatedAt is the unix second of the most recent write to the formation.
`nextStages`	body	string[]	—	NextStages are the stages reachable from the formation's current stage, whether or not their guards are satisfied yet.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo company structure

.ts

.py

.go

.rs

.java

import { Configuration, CompanyApi } from 'hanzoai';

const api = new CompanyApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.putCompanyStructure({ jurisdiction: "<jurisdiction>", name: "<name>" });

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = CompanyApi(client).put_company_structure(jurisdiction="<jurisdiction>", name="<name>")

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

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

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

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

let result = company_api::put_company_structure(&cfg, Default::default()).await?;

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

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

var result = new CompanyApi(client).putCompanyStructure();

curl -X PUT https://api.hanzo.ai/v1/company/structure \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jurisdiction": "<jurisdiction>",
       "name": "<name>"
     }'

MCP reaches company through the company tool, which names its 22 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_companies"
         }
       }
     }'

Company API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousCreate company NextGet accreditation