The four things that get cleared
People confuse these constantly, so it’s worth separating them up front. They are not the same gate.
All four must be clear. A
VERIFIED party with a FLAGGED wallet still cannot move money — see Wallet readiness.
Your company tenant is provisioned by Venly, not through the API. If it isn’t, every verification call fails with
verification-not-provisioned — and no amount of retrying will fix it. See Troubleshooting.Party vs. account
A party’sstatus is ACTIVE the moment you create it. That is not verification. It means the record is usable, not that the person behind it has been identified.
The account’s
kycStatus is what every money-movement endpoint checks. It follows from its account-holder party’s verification.
Pick a route
Two routes carry a production integration, and which you can use is mostly decided for you:Hosted verification link
Venly hosts the flow; you hand over a URL. Works for individuals and organisations. The default.
Sumsub token sharing
Forward a verification you already ran in your own Sumsub account. Individuals on self-custody only.
There is a third path, tenant-managed KYC, where
you declare
kycStatus: NOT_REQUIRED on the account and Venly doesn’t gate on its own verification.It is not something you can switch on yourself: a Venly admin has to enable the flag on your company
tenant, and without it the call fails with kyc-not-required-not-allowed. In practice it’s granted for
testing rather than production use, so plan your production integration around a hosted link or Sumsub
token sharing and treat tenant-managed KYC as a way to exercise money movement without real
verifications.Verdicts are asynchronous
No verification route returns a verdict inline. In every case you create or forward something, get an acknowledgement, and the outcome lands later. That shapes your integration: build the pending state in from the start. Don’t write code that assumes a party is verified immediately after you mint a link.1
Trigger verification
Mint a link, or forward a token at account creation.
2
Wait
Register a webhook so the verdict is pushed to you. Polling
Get a party works, but verdicts are
human-paced — polling for hours is wasteful.
3
Read the outcome
kycStatus (individuals) or kybStatus (organisations) on the party; kycStatus on the account
for the money-movement gate.What you can do while unverified
Plenty. Verification blocks money movement, not setup:
Front-load that left column while verification is in flight.
Next steps
Roles & entities
Company, party, account, and role — which object holds what.
Individual KYC
Verifying a natural person.
Business KYB
Verifying a company or business.
Troubleshooting
Every verification error code and what to do about it.