Start KYB for a corporate
/corporates/kyb Use this to begin verification for a corporate. A corporate can't create instruments or move money until due diligence is approved.
It starts the KYB process for the logged-in corporate and returns a reference. Verification itself is
carried out by a KYB provider, not through this API. Embed the KYB UI Component in your application
and initialize it with that reference to show the provider's screens to the corporate.
Prerequisites
The corporate's root user must have verified their email address first, or the request fails with
EMAIL_UNVERIFIED. See
Verify email of the corporate root user.
Managed onboarding
On managed-onboarding programmes, MANAGED_ONBOARDING_PENDING means Weavr is still
preparing the corporate's KYB case. Wait for the corporate KYB status webhook with a
COLLECTION.READY_TO_START run, then call this endpoint. The call succeeds and the
same run continues when the corporate opens the KYB UI Component.
Calling it more than once
The request fails with KYB_ALREADY_APPROVED if the corporate is already verified, KYB_PENDING_REVIEW
while a submission is under review, and KYB_PERMANENTLY_REJECTED if it was turned down for good. Read
the current status with Get KYB for a corporate before
starting, and treat these conflicts as "no action needed" rather than retrying.
Tracking the outcome
This call only opens the process; approval happens asynchronously once the corporate completes the
provider's flow. Poll Get KYB for a corporate or subscribe
to the KYB status webhook. Use corporateKybStatus for the corporate's acceptance to use financial
services, and kybRuns for detailed progress.
Authorized signatories
KYB covers the corporate itself. Individuals who act as legal representatives are verified separately once KYB is approved. See Start signatory verification.
Read Corporate due diligence and KYB for the full flow.
Request
Responses
Success
{ "reference": "123456789"}