Start KYC for a consumer

Use this to begin identity verification for a consumer. A consumer can't create instruments or move money until due diligence is approved.

It starts the KYC process for the logged-in consumer and returns a reference. Verification itself is carried out by a KYC provider, not through this API. Embed the KYC UI Component in your application and initialize it with that reference to show the provider's screens to the user.

Prerequisites

The consumer's root user must have verified their email address first, or the request fails with EMAIL_UNVERIFIED. See Verify email of the consumer root user.

Fields

prefillDetails lets you pass details you already hold as name/value pairs, so the user doesn't re-enter them in the provider's screens.

Calling it more than once

KYC starts once per outcome. The request fails with KYC_ALREADY_APPROVED if the consumer is already verified, KYC_PENDING_REVIEW while a submission is under review, and KYC_REJECTED if it was turned down. Read the current status with Get KYC for a consumer 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 user completes the provider's flow. Poll Get KYC for a consumer, where fullDueDiligence moves through NOT_STARTED, INITIATED, PENDING_REVIEW, and then APPROVED or REJECTED. The consumer can transact once it is APPROVED.

Read Consumer due diligence and KYC for the full flow.