Hanzo
OpenapiCompany

StartKYC opens an identity-verification session for every founder with the…

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

Addresshttps://api.hanzo.ai/v1/company/kyc
MethodPOST
Operationpost_company_kyc
AuthAuthorization: Bearer $HANZO_API_KEY

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

Request

The document declares no body for POST /v1/company/kyc. 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_kyc, which answers from the running route.

Response

StatusBodyMeaning
200kycStartOutok

200 body — 44 fields.

FieldInTypeAlwaysDescription
formationbodyFormation
formation.alreadyIncorporatedbodybooleanAlreadyIncorporated declares an org that already has a legal entity, which takes the import path (structure → import → company) instead of forming one.
formation.capTableImportedbodybooleanCapTableImported reports whether the existing company's cap table has been imported onto the canonical cap table.
formation.createdAtbodyintegerCreatedAt is the unix second the formation was opened.
formation.documentIdsbodystring[]DocumentIDs are the data room ids of the GENERATED formation documents.
formation.esignRefbodystringEsignRef is the e-signature provider's reference for the signature request.
formation.filingbodyFiling
formation.filing.atbodyintegerAt is the unix second the filing record was written.
formation.filing.notebodystringNote explains a filing Hanzo did not perform itself: what remains to be done and by whom.
formation.filing.providerbodystringProvider is the filing partner that performed the filing, or "manual" when no partner is wired.
formation.filing.refbodystringRef is the partner's or the state's filing reference.
formation.filing.statusbodystringStatus 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.foundersbodyFounder[]Founders is every founding stakeholder, with its equity split and KYC state.
formation.founders[].decidedBybodystringDecidedBy is who settled a terminal KYC status: the provider name, or a reviewer's user id.
formation.founders[].emailbodystringEmail 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[].equityBpsbodyintegerEquityBps is the founder's ownership in basis points, 0–10000 (1% == 100 bps, so 10000 is the whole company).
formation.founders[].kycRefbodystringKYCRef is the idv provider's session reference for this founder.
formation.founders[].kycStatusbodystringKYCStatus is the founder's identity-verification state: pending, verified (a real idv provider reported a pass), reviewer_confirmed (a privileged reviewer…
formation.founders[].namebodystringName is the founder's full legal name, as it appears on the formation documents.
formation.genesisbodyGenesis
formation.genesis.atbodyintegerAt is the unix second the genesis root was computed.
formation.genesis.blockbodyintegerBlock is the L1 block the anchoring transaction landed in.
formation.genesis.chainIdbodyintegerChainID is the EVM chain the root is committed to — the Hanzo L1 by default.
formation.genesis.notebodystringNote explains an unanchored genesis honestly — anchor wiring absent, or the submit error — rather than reporting a commit that did not happen.
formation.genesis.rootbodystringRoot is the 0x-prefixed keccak256 root of the founding allocation.
formation.genesis.statusbodystringStatus is pending (root computed, not yet on-chain) or anchored (committed).
formation.genesis.txHashbodystringTxHash is the L1 transaction hash of the anchoring commit.
formation.importedbodybooleanImported reports whether the existing company's corporate documents have been ingested into the org's data room.
formation.importedDocsbodystring[]ImportedDocs are the data room ids of the documents ingested from Drive.
formation.jurisdictionbodystringJurisdiction is the state of formation: DE or WY.
formation.namebodystringName is the company name the entity is being formed under.
formation.orgbodystringOrg is the owning org — the tenant key, and the reason there is exactly one formation per org.
formation.paidbodybooleanPaid reports whether the one-time formation fee has been charged.
formation.paymentRefbodystringPaymentRef is the billing reference recorded for the charged formation fee on the org's own ledger.
formation.signedbodybooleanSigned reports whether the formation documents have come back signed — the e-signature provider's answer, which a real provider's webhook drives.
formation.stagebodystringStage 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.structurebodystringStructure is the legal entity being formed: c-corp, llc or dao-llc.
formation.updatedAtbodyintegerUpdatedAt is the unix second of the most recent write to the formation.
providerbodystringProvider is the wired identity-verification provider's name.
sessionsbodykycSession[]Sessions is one entry per founder, in the order the founders are recorded.
sessions[].emailbodystringEmail is the founder the session belongs to.
sessions[].refbodystringRef is the provider's reference for the session.
sessions[].statusbodystringStatus is the session's status at start, which is always pending.
sessions[].verifyUrlbodystringVerifyURL is the hosted flow the founder visits; empty for the manual provider.

Failure carries the platform error shape — see Errors.

Examples

hanzo company kyc create

Company API · All Hanzo APIs · Interactive reference

How is this guide?

On this page