Company
Package company is incorporation end to end: pick a structure, add founders, pay, file, and e-sign.
Package company is incorporation end to end: pick a structure, add founders, pay, file, and e-sign.
| Base URL | https://api.hanzo.ai |
| Operations | 22 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
company
Advance runs the ONE guarded transition of the formation machine.
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. |
GenerateDocuments 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.
POST /v1/company/documents
GenerateDocuments 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.
CompleteEsign records whether the formation documents have been signed.
POST /v1/company/esign/complete
CompleteEsign 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. |
RequestEsign sends the generated formation documents for signature by every founder and records the provider's reference on the formation.
POST /v1/company/esign
RequestEsign 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.
SetFounders replaces the formation's founders.
POST /v1/company/founders
SetFounders 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 | cloud_Founder[] | — | Founders is every founding stakeholder. Each needs a name and an email, and equityBps between 0 and 10000 (1% == 100 bps |
post_v1_company_fundraise_deck
POST /v1/company/fundraise/deck
RecordRound records a fundraising round on the org's canonical cap table.
POST /v1/company/fundraise/round
RecordRound 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. |
RequestSafe raises an e-signature request over documents already in the org's data room — a SAFE, a convertible note, or any other fundraising paper.
POST /v1/company/fundraise/safe
RequestSafe 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 | cloud_Signer[] | — | Signers are the recipients, each a name and an email. |
RecordGenesis 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.
POST /v1/company/genesis
RecordGenesis 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.
ImportCapTable reads an existing company's cap table from a Google Sheet and adds its stakeholders to the canonical cap table.
POST /v1/company/import/captable
ImportCapTable 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. |
ImportDocuments ingests an existing company's corporate documents from a Google Drive folder into the org's data room.
POST /v1/company/import/documents
ImportDocuments 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. |
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.
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. |
RefreshKYC reconciles each pending founder's KYC with the WIRED provider — the PULL path to a provider-reported terminal status.
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.
StartKYC opens an identity-verification session for every founder with the wired provider and records each session's reference on the formation.
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
POST /v1/company/payment
SummarizeRegister 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.
GET /v1/company/register/summary
SummarizeRegister 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.
ListRegister returns the platform's whole formation register, newest activity first — every org's formation, not the caller's.
GET /v1/company/register
ListRegister 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. |
ReviewQueue reports the founders whose KYC is not yet settled, oldest formation first, so the queue drains in the order founders have been waiting.
GET /v1/company/review
ReviewQueue 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. |
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.
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.
SetStructure records the entity kind, the state of formation and the proposed name.
PUT /v1/company/structure
SetStructure 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 returns the caller org's formation and the stages reachable from it, or 404 when the org has not begun one.
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.
Begin starts the org's one formation and returns it with the stages reachable from it.
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) inst |
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. |
How is this guide?