- Some partners rely on Venly’s verification. The compliance checks happen on our side, through the identity verification your customer already completed.
- Other partners run their own KYC or KYB. We pass on your customer’s verified data, and the
partner reviews it before accepting them. Sometimes the partner needs more from your customer
directly.
requiredActionstells you when that happens.
409 partner-onboarding-pending or
422 partner-onboarding-rejected.
If that is where your customer is stuck, this page walks you through finding out why and what to do
about it.
Rule out the other two gates
The gates are independent. A party can be
VERIFIED, have ACCEPTED the terms, and still be PENDING
with the partner. If either of the first two isn’t cleared, fix that first. Partner onboarding can’t
start until the party is verified.
Read the partner-onboarding status
Response (200)
status tells you which situation
you are in:
The same
status is also on the party as partnerOnboardingStatus, so
Get a party shows it too. requiredActions is
only returned by this endpoint.
Not started: start onboarding
Onboarding starts the first time you try to provision. You can also start it yourself:202 with the same body as the read, normally PENDING, and
you poll the read endpoint for the outcome. While onboarding is PENDING or APPROVED, calling it
again changes nothing.
If the party doesn’t qualify yet, you get a retryable 409:
Partner onboarding is for individuals only. For an
ORGANISATION you get 400 party-type-not-supported,
and retrying won’t help.
Pending: is the partner waiting on your customer?
Look atrequiredActions. It is always present:
- Empty (
[]): there is nothing for your customer to do right now. The partner is working on it, possibly reviewing something your customer already submitted. Keep polling;statusmoves on by itself. - Not empty: the partner can’t finish until your customer completes each listed step.
More
reason values may be added. Treat an unknown value like IDENTIFICATION, and don’t fail on it.
Each entry has a url to the partner’s hosted flow. Give it to your customer, who opens it and
completes the step there. You don’t need to tell Venly when they’re done: once the partner approves,
status moves to APPROVED by itself.
The link can change between calls. It is resolved live on every read, which is why both
partner-onboarding responses are sent with Cache-Control: no-store. Always use the one from your
latest call, and never cache or store it.
A simple way to handle this in your product:
- Poll
GET /parties/{partyId}/partner-onboarding. - While
statusisPENDINGandrequiredActionsis not empty, show your customer a “complete your verification” prompt that opens the latesturl. - Keep polling until
statusisAPPROVED, then provision.
Rejected: retry once the cause is fixed
REJECTED is not final. Once the underlying problem is resolved, for example corrected details or a
re-run verification, call POST again to re-attempt onboarding. You don’t need Venly for this.
Provisioning answers 422 partner-onboarding-rejected until the party is approved.
Avoiding the wait next time
CallPOST /parties/{partyId}/partner-onboarding as soon as a customer’s verification clears, while
they are still in your onboarding flow. It is usually APPROVED by the time they ask for bank details.
If the partner needs something from them, requiredActions shows it while they’re still there to act
on it.
Next steps
Partner-terms consent
The gate that comes just before this one.
Virtual bank accounts
The first thing partner onboarding unblocks.
Troubleshooting verification
Which onboarding errors are worth retrying and which aren’t.
Onboarding lifecycle
All the states, from a new party to an account that can move money.

