KYB steps and configuration

A KYB flow is no longer a single step. It is an anchor step that collects business information, plus optional satellite steps that collect documents, beneficial owners, and directors. All of them write into one shared KYB result, so the reviewer still sees a single case.

This page is the reference for the step types, what each one configures, and the endpoints the applicant's session posts to. For the dashboard walkthrough and the review workflow, see the KYB overview.

Breaking changes in this release

• The flow no longer has a webhookUrl. Destinations are organization-level webhook endpoints — see Webhook endpoints.
• discoveryEnabled and discoveryBudgetCredits moved from the KYB_UBOS step's config onto the anchor KYB step's config. Existing flows were migrated in place; nothing to do unless you build flow configuration yourself.
• The extend-discovery response shape changed. See Ownership discovery.

The anchor and its satellites

Step type	Role	Requires
KYB	Anchor. Collects the business information and owns the shared KYB result. Also where ownership discovery is turned on.	—
KYB_DOCUMENTS	Company document uploads.	A KYB step earlier in the flow
KYB_UBOS	Beneficial-owner declaration.	A KYB step earlier in the flow
KYB_DIRECTORS	Director declaration.	A KYB step earlier in the flow

Each satellite carries a kybStepId pointing back at its anchor, the same way a Liveness step points at its Document Verification step. Two rules are enforced when you save a flow:

• A flow has at most one KYB anchor.
• A satellite's kybStepId must resolve to a KYB step ordered before it.

A satellite without a resolvable anchor is not a valid flow.

Splitting the step buys three things:

• The applicant can be routed part by part. Documents can be collected before owners, or a part can be skipped entirely for a particular flow.
• UBOs and directors can use different KYC flows. Each satellite carries its own kycFlowId, so directors can be invited into a lighter flow than beneficial owners.
• Owners or directors can be collected without KYC at all. See requireKyc below.

A KYB step with no satellites

An anchor with no satellite steps is valid as long as its own configuration declares nothing else to collect: no upfront-required document and collectDirectors off. That is a split flow whose only part is the anchor — the applicant supplies business information and the result goes straight to moderation.

An anchor with no satellites that does still declare documents or directors is a legacy monolithic step. It keeps working unchanged through the legacy submission endpoint, and the per-part endpoints reject it with a message telling you which endpoint to use instead.

Configuration

KYB (anchor)

Field	Type	Default	Meaning
discoveryEnabled	boolean	false	Dispatch ownership discovery when business information is submitted. Moved here from KYB_UBOS.
discoveryBudgetCredits	integer	—	Per-verification cap on discovery spend, in credits. Omit for the platform default. Only read when discoveryEnabled is on.
agenticMode	enum	DISABLED	KYB agent mode: DISABLED, SUGGEST, AUTO_PILOT. See KYB Agent Mode.
amlAgenticMode	enum	DISABLED	AML agent mode for the company and UBO screenings this step triggers.
allowIndividualSubject	boolean	false	Offer the applicant an individual-vs-business choice at the start of the step.
labels	object	{}	Per-locale button labels.

An anchor on a legacy monolithic flow also carries kycFlowId, maxUbos, maxDirectors, maxFileUploads, collectDirectors, autoSendUboKycEmail, and the document configuration described below. On a split flow those live on the satellites instead.

KYB_DOCUMENTS

Field	Type	Default	Meaning
kybStepId	UUID	—	The anchor this satellite belongs to. Required.
maxFileUploads	integer	10	How many additional documents the applicant may attach.
certificateOfIncorporation, articlesOfAssociation, organizationalStructureChart	object	—	Built-in documents. Each can be marked required, or resolved on demand.
proofOfAttorney	object	—	Built-in, but always on demand: never requested upfront, never gates submission or approval. A reviewer asks for it during review.
customDocuments	array	—	Your own document types.
customCountryDocuments	object	{}	Per-country overrides, keyed by ISO 3166-1 alpha-2. Replaces the global list for matching countries.
labels	object	{}	Per-locale button labels.

The effective per-country document list served to the client (documentsPerCountry) is resolved at runtime by merging Zyphe's platform definitions with your customCountryDocuments; yours win per country.

KYB_UBOS

Field	Type	Default	Meaning
kybStepId	UUID	—	The anchor this satellite belongs to. Required.
maxUbos	integer	10	Maximum number of beneficial owners the applicant may declare.
requireKyc	boolean	true	Whether each declared owner must complete a KYC flow. See below.
kycFlowId	UUID	—	The flow owners are invited into. Only meaningful when requireKyc is on; may be omitted otherwise.
autoSendUboKycEmail	boolean	true	Send the KYC invitation automatically on submission. When off, a reviewer sends the first invitation from the result page.
labels	object	{}	Per-locale button labels.

KYB_DIRECTORS

Field	Type	Default	Meaning
kybStepId	UUID	—	The anchor this satellite belongs to. Required.
maxDirectors	integer	10	Maximum number of directors the applicant may declare.
requireKyc	boolean	true	Whether each declared director must complete a KYC flow.
kycFlowId	UUID	—	The flow directors are invited into. Independent of the UBO satellite's, so directors can use a different KYC flow.
labels	object	{}	Per-locale button labels.

The existence of the KYB_DIRECTORS step is what makes a split flow collect directors. The anchor's collectDirectors boolean is the legacy monolithic equivalent.

Collecting people without KYC

requireKyc is on the UBO and director satellites, and defaults to true — which is what every flow built before it existed does.

requireKyc: true. The widget demands an email address for each person, because an email is what a KYC invitation is addressed to. Zyphe sends and schedules those invitations against kycFlowId, and the person must complete that flow before the KYB can be approved.

requireKyc: false. The widget collects the person by name alone and asks for no email. kycFlowId becomes meaningless and can be omitted. The person is still screened for PEP and sanctions by name; there is simply no identity verification behind the name.

The two satellites are independent: you can require KYC of beneficial owners while screening directors by name only, or the reverse.

Two rules follow from it:

• Saving a step with requireKyc: true and no kycFlowId is rejected at validation time. Set one, or turn requireKyc off.
• With requireKyc: true, a final submission whose declared people carry no email is rejected. This also applies to the legacy monolithic endpoint, so a widget that used to send name-only owners against a KYC-requiring step must now send emails — or the step must set requireKyc: false.

The readiness gate keys off the person, not the config

Approval readiness is decided per person, from whether that person has an email on file — an email-bearing person needs a completed KYC, a name-only person needs a clean name screening. Changing requireKyc therefore does not retroactively re-gate people already declared, and owners found by ownership discovery — who arrive without an email — are always screened by name.

Which population must be screened

A KYB result records a screening strategy — which population of natural persons must be identified and screened before it can be approved:

Value	Meaning
ubo	Beneficial owners. The default, and correct for the overwhelming majority of private companies.
directors	Directors instead of owners. For a business where no natural person crosses the ownership threshold — a listed or widely-held company, a state-owned body — control rather than ownership is the screenable population.
uboAndDirectors	Both.

The strategy selects which population is required, never whether one is: every value demands at least one screened natural person, so no sequence of changes produces a KYB that is approvable with nobody identified.

It gates the agent approval path and the automatic completion path — both refuse a file whose strategy is unsatisfied. A human reviewer approving the result is deliberately not gated by it: the override is theirs to make, and it is recorded as theirs.

Agents change it through the set_kyb_screening_strategy MCP tool, which accepts only a strategy the people already on file satisfy, requires a reason, and writes a KYB_SCREENING_STRATEGY_CHANGED entry to the audit trail carrying the previous and new strategy, the reason, and the UBO and director counts at that moment. Ask Zyphe support to set it for a flow if you are not driving KYB through an agent.

Alongside it, the result records a due-diligence level — simplified, standard (the default), or enhanced — supplied as an optional dueDiligenceLevel on the approve call and written in the same transaction that approves the file. simplified is never a fallback: it is a positive finding about the subject, so an unclassified file is standard, not reduced-checks. Recording the tier is currently all the platform does with it; no check varies by level yet.

Submitting each part

The applicant's session posts one part at a time. All four endpoints are verification-request scoped and authenticated with the session token the hosted widget already holds — they are not part of the API-key /sdk surface. Add ?sandbox=true to target the sandbox.

Method	Path	Body	Step the VR must be on
POST	/flow/{flow_id}/vr/{verification_request_id}/kyb/submit-business-info	businessInformation, submit	KYB
POST	/flow/{flow_id}/vr/{verification_request_id}/kyb/submit-documents	documentUploads, submit	KYB_DOCUMENTS
POST	/flow/{flow_id}/vr/{verification_request_id}/kyb/submit-ubos	uboDefinitions, submit	KYB_UBOS
POST	/flow/{flow_id}/vr/{verification_request_id}/kyb/submit-directors	directorDefinitions, submit	KYB_DIRECTORS

Each returns 202 with verificationRequestId and kybResultId. submit-documents additionally returns documentUploads carrying presigned PUT URLs — upload the files to those URLs immediately after the response returns.

The shared KYB result stays in ACQUIRING until every part present in the flow has been submitted; only then does it move on. Reading any satellite's verification request returns the shared kybResult, so a client does not have to hold the anchor's id to show progress.

The two-phase submit flag

Each payload carries a submit boolean, defaulting to true:

• submit: false saves progress. The part stays open and the applicant can come back to it.
• submit: true marks the part submitted and attempts the shared KYB transition. Once every part of the flow is submitted, the KYB result moves on to enrichment and moderation.

Use submit: false for autosave and multi-screen parts; send submit: true on the last screen of the part.

A final submit runs the part's real validation, which a draft save skips:

Part	What a final submit enforces
Business info	Company screening is queued; the document part is reopened if resolving the company's country made more documents required; ownership discovery is dispatched when enabled.
Documents	Every required document for the resolved country must be present. documentUploads: null on a final submit means "finalize what was already saved" — it never clears them.
UBOs, directors	Caps from maxUbos / maxDirectors. When requireKyc is on, every declared person must carry an email address, otherwise the call is rejected. Any outstanding declaration request for that part is fulfilled.

Non-registered businesses

businessInformation on submit-business-info is nullable. Send null for a business that is not registered — the sole-proprietor path that collects a single owner directly.

The legacy monolithic endpoint

POST /flow/{flow_id}/vr/{verification_request_id}/kyb/process-kyb-document is unchanged and remains the submission path for a monolithic KYB step. It enforces the same validation and upload caps as the split endpoints. Posting a per-part submission to a monolithic flow returns a 400 naming this endpoint.

Prefilling from official registers

Two applicant-facing endpoints let the widget prefill the business-information form from official business registers before the applicant confirms it:

Method	Path	Purpose
GET	.../kyb/company-search?country=&query=	Search by company name or registration number. Returns candidates.
POST	.../kyb/company-prefill	Fetch a chosen candidate's details as prefill values.
GET	.../kyb/director-candidates	Re-read any director suggestions from the persisted snapshot.

company-search returns available: false with an empty candidate list when no source serves that country. That is not an error — the widget hides the search box. company-prefill returns authoritative: false when the values came from a non-authoritative search hit; the authoritative record is fetched after submission and the cross-check compares the applicant's submission against it.

Director candidates are commonly empty, since officer data is not always available for a country. Treat an empty list as normal and collect directors from the applicant.

These endpoints are rate limited per verification request: 30 searches and 10 prefills per minute.

Step outputs in Flow Builder

Each satellite writes its own step output, which Flow Builder conditions can branch on:

Step	Output fields
KYB	status, moderationStatus, pepAndSanctionsStatus, businessName, registrationNumber, country, amlPep, amlSanctions, amlRiskScorePercent
KYB_DOCUMENTS	uploadedCount, requiredSatisfied
KYB_UBOS	uboCount, allUbosVerified
KYB_DIRECTORS	directorCount, allDirectorsVerified

Related

• KYB overview — creating a flow, the applicant experience, reviewing results
• Ownership discovery — automatic UBO discovery and graph expansion
• KYB Agentic Review Engine
• Webhook endpoints — where KYB results are delivered