Seeds the canonical cap table with the founding allocation (stakeholders, a…

Seeds the canonical cap table with the founding allocation (stakeholders, a common share class, issued shares) and anchors the deterministic…

POST /v1/company/genesis

Company → · All API references → · Six flows, four surfaces →


Address	`https://api.hanzo.ai/v1/company/genesis`
Method	`POST`
Operation	`post_company_genesis`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Seeds the canonical cap table with the founding allocation (stakeholders, a common share class, issued shares) and anchors the deterministic equity-genesis root on-chain.

It is idempotent: once a root is recorded the cap table is NOT re-seeded, which would double-issue founder share certificates. The root is persisted even when the on-chain submit fails, because the root is the tamper-evident witness and must not be recomputed on retry. Available only at the genesis stage.

Request

The document declares no body for POST /v1/company/genesis. The handler is typed in cloud but its shape is not yet emitted, so the fields are not listed here — ask the MCP door's describe for post_company_genesis, which answers from the running route.

Response

Status	Body	Meaning
`200`	formationView	ok

200 body — 39 fields.

Field	In	Type	Always	Description
`formation`	body	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	—	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	Filing	—
`formation.filing.at`	body	integer	—	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…
`formation.founders`	body	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	—	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…
`formation.founders[].name`	body	string	—	Name is the founder's full legal name, as it appears on the formation documents.
`formation.genesis`	body	Genesis	—
`formation.genesis.at`	body	integer	—	At is the unix second the genesis root was computed.
`formation.genesis.block`	body	integer	—	Block is the L1 block the anchoring transaction landed in.
`formation.genesis.chainId`	body	integer	—	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…
`formation.structure`	body	string	—	Structure is the legal entity being formed: c-corp, llc or dao-llc.
`formation.updatedAt`	body	integer	—	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

hanzo company genesis

import { Configuration, CompanyApi } from 'hanzoai';

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

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).post_company_genesis()

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

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

use hanzo_cloud::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::post_company_genesis(&cfg, Default::default()).await?;

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

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

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

curl -X POST https://api.hanzo.ai/v1/company/genesis \
  -H "Authorization: Bearer $HANZO_API_KEY"

The door reaches company through the company tool, which names its 22 operations with its own verbs — this one among them, under a name only the door 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": "get_company"
         }
       }
     }'

Company API · All Hanzo APIs · Interactive reference

Seeds the canonical cap table with the founding allocation (stakeholders, a…

Request

Response

Examples

On this page