Company

Package company is incorporation end to end: pick a structure, add founders, pay, file, and e-sign.

All API references → · Six flows, four surfaces →


Base URL	`https://api.hanzo.ai`
Operations	22
Auth	`Authorization: Bearer $HANZO_API_KEY`

`POST /v1/company/advance`

Advance runs the ONE guarded transition of the formation machine. It is the only door between stages: the actions populate data, this decides ordering.

An edge the machine does not define answers 409; an edge whose guard is not yet satisfied answers 422 naming what is missing. Reaching the terminal company stage also records the incorporation on the canonical cap table, and that must succeed before the transition is persisted.

Request body — application/json (required)

Field	Type	Required	Description
`to`	string	—	To is the target stage: structure, founders, payment, documents, esign, genesis, import or company.

`POST /v1/company/documents`

Renders the formation documents for the chosen structure and jurisdiction, ingests each into the org's data room, and submits the state filing through the filing seam.

With no filing partner wired the filing is recorded honestly as "manual" — no filing id is fabricated. Available only at the documents stage.

`POST /v1/company/esign/complete`

Records whether the formation documents have been signed. It consults the e-signature provider, which a real provider's webhook drives; the signal is idempotent.

An explicit signed in the request overrides the provider's answer, which is the manual path for the stub provider that never self-completes.

Request body — application/json (required)

Field	Type	Required	Description
`signed`	boolean	—	Signed, when present, overrides what the provider reports — the manual path for a provider whose webhook is not wired.

`POST /v1/company/esign`

Sends the generated formation documents for signature by every founder and records the provider's reference on the formation. Available only at the esign stage.

`POST /v1/company/founders`

Replaces the formation's founders. Each founder needs a name, an email and an equity share in basis points; every founder is (re)set to pending KYC, so a previously settled decision does not survive a change of the list.

Request body — application/json (required)

Field	Type	Required	Description
`founders`	Founder[]	—	Founders is every founding stakeholder. Each needs a name and an email, and equityBps between 0 and 10000 (1% == 100…

`POST /v1/company/fundraise/deck`

Share a pitch deck in the org's data room

Stores the request body as a document in the caller org's data room and answers with the data room id to reference it by. The deck is RAW BYTES of whatever content type is sent — a PDF, a slide export — not a JSON document: the Content-Type header is carried through to the data room as given, and ?name= names the document, defaulting to pitch-deck.

Scoped to the caller's validated org, and only after incorporation: a formation still short of stage company is refused 409 and an org that never began one is 404. The route is registered AHEAD of the surface's JSON body cap deliberately, so a deck's size ceiling is the edge's rather than the cap meant for small structured records. An empty body is 400; a data room that will not take the bytes is 502.

`POST /v1/company/fundraise/round`

Records a fundraising round on the org's canonical cap table. Available only after incorporation (stage company); roundType defaults to PRICED.

Request body — application/json (required)

Field	Type	Required	Description
`name`	string	—	Name is the round's name on the cap table, e.g.
`preMoneyValuation`	number	—	PreMoneyValuation is the valuation the round prices off, before the new money.
`pricePerShare`	number	—	PricePerShare is the per-share price of a priced round.
`roundType`	string	—	RoundType is PRICED, SAFE or CONVERTIBLE_NOTE.
`shareClassId`	string	—	ShareClassID is the cap table's share class the round issues into.
`targetAmount`	number	—	TargetAmount is the amount the round is raising, recorded verbatim on the canonical cap table's rounds.create contract.

`POST /v1/company/fundraise/safe`

Raises an e-signature request over documents already in the org's data room — a SAFE, a convertible note, or any other fundraising paper. Available only after incorporation (stage company).

Request body — application/json (required)

Field	Type	Required	Description
`documentIds`	string[]	—	DocumentIDs are data room document ids to raise a signature request over.
`signers`	Signer[]	—	Signers are the recipients, each a name and an email.

`POST /v1/company/genesis`

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.

`POST /v1/company/import/captable`

Reads an existing company's cap table from a Google Sheet and adds its stakeholders to the canonical cap table.

The first row is a header and columns are matched by name (case-insensitive): name and email are required, type/relationship/institution optional. A sheet without name and email columns, or with no usable data rows, is refused with 400. Available only at the import stage.

Request body — application/json (required)

Field	Type	Required	Description
`range`	string	—	Range is an optional A1 range within the sheet; empty reads the default range.
`spreadsheetId`	string	—	SpreadsheetID is a Google Sheets id.

`POST /v1/company/import/documents`

Ingests an existing company's corporate documents from a Google Drive folder into the org's data room. The import is shallow — sub-folders are skipped, not walked — and available only at the import stage.

Request body — application/json (required)

Field	Type	Required	Description
`folderId`	string	—	FolderID is a Google Drive folder id.

`POST /v1/company/kyc/decision`

DecideKYC records a privileged reviewer's MANUAL decision on a founder's KYC — the human-in-the-loop path, and the ONLY route to a pass when no real provider is wired. It produces a DISTINCT reviewer_confirmed, never a provider "verified".

Because Hanzo forms the entity and carries the formation KYC/AML obligation, the reviewer is a HANZO platform reviewer (SuperAdmin), and the decision is ATTRIBUTED to them.

Request body — application/json (required)

Field	Type	Required	Description
`email`	string	—	Email identifies the founder on the formation.
`status`	string	—	Status is the decision: reviewer_confirmed or failed.

`POST /v1/company/kyc/refresh`

RefreshKYC reconciles each pending founder's KYC with the WIRED provider — the PULL path to a provider-reported terminal status. For the manual provider the check stays pending; for a real provider it reflects the settled decision, ATTRIBUTED to the provider.

It NEVER trusts a client-asserted status — the status comes from the provider seam — so a client cannot force a pass here, and an already-passing founder (e.g. a reviewer confirmation) is left untouched.

`POST /v1/company/kyc`

StartKYC opens an identity-verification session for every founder with the wired provider and records each session's reference on the formation.

A start is never a decision: any terminal status the provider reports at inquiry time is clamped back to pending, so the payment gate can never open here. A terminal status arrives only from POST /v1/company/kyc/refresh (the provider) or POST /v1/company/kyc/decision (a Hanzo platform reviewer).

`POST /v1/company/payment`

Charge the one-time formation fee and mark the formation paid

Bills the caller's own org the one-time Hanzo Company formation fee — $999 unless the deployment sets another — and answers with the formation record carrying its paid flag and the charge reference. Takes no body: the org is the validated tenant and the amount is the platform's, never the caller's to assert.

IDEMPOTENT on the formation rather than on the request: an already-paid formation answers 200 with the same record and is not charged again, so a retry or a double-clicked button costs nothing. Available only at the payment stage (409 anywhere else) and only for an org that has begun a formation (404 otherwise).

A refused charge answers the fleet-wide billing contract, not a formation error — 402 when the org cannot pay, 503 when metering is unavailable — which is exactly why this route is not a typed op.

`GET /v1/company/register/summary`

Counts the platform's formations by stage — the register's shape in one read, so a queue that is growing is visible as a number rather than inferred by paging the list. A Hanzo platform operation: a caller who is not a platform reviewer gets 403.

`GET /v1/company/register`

Returns the platform's whole formation register, newest activity first — every org's formation, not the caller's. It is a Hanzo platform operation: a caller who is not a platform reviewer gets 403.

Filter by stage and structure, page with limit and offset. An unknown stage is refused with 400 rather than returning a silently empty page.

Parameter	In	Type	Required	Description
`stage`	query	string	—	Stage keeps only formations at that stage.
`structure`	query	string	—	Structure keeps only formations of that entity kind.
`limit`	query	integer	—	Limit bounds the page; 0 or less means the default of 200.
`offset`	query	integer	—	Offset skips that many rows.

`GET /v1/company/review`

Reports the founders whose KYC is not yet settled, oldest formation first, so the queue drains in the order founders have been waiting. A Hanzo platform operation: a caller who is not a platform reviewer gets 403.

It only says who is waiting; the decision itself is POST /v1/company/kyc/decision.

Parameter	In	Type	Required	Description
`limit`	query	integer	—	Limit bounds how many formations are scanned; 0 or less means the default of 200.

`POST /v1/company/skip`

Skip marks the org as already incorporated and moves it onto the import path, so an existing company brings its documents and cap table in instead of forming a new entity. Available only at the structure stage.

`PUT /v1/company/structure`

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 body — application/json (required)

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

`GET /v1/company`

Get returns the caller org's formation and the stages reachable from it, or 404 when the org has not begun one.

`POST /v1/company`

Begin starts the org's one formation and returns it with the stages reachable from it. It is idempotent: an org that already has a formation gets that one back with 200, while a first call creates it and answers 201.

Request body — application/json (required)

Field	Type	Required	Description
`alreadyIncorporated`	boolean	—	AlreadyIncorporated declares an org that already has an entity, which takes the import path (POST /v1/company/skip)…
`jurisdiction`	string	—	Jurisdiction is the state of formation: DE or WY.
`name`	string	—	Name is the proposed company name.
`structure`	string	—	Structure is the legal entity to form: c-corp, llc or dao-llc.

All Hanzo APIs · Interactive reference

Company

On this page