A CKYC 2.0 integration is four API families called in a fixed order: Search the registry for an existing record, capture OTP-based consent, Download the record against the KIN, and Upload or Update when no usable record exists. The parts that break integrations are rarely the API calls. They are the consent step, mandatory Aadhaar masking before submission, and the validation rules that turn a working request into a rejected one.

This is the build guide. For what CKYC is and why the registry is being rebuilt, start with CKYC 2.0: India's real-time KYC shift for developers.

NamoID is an India-ready OAuth/OIDC identity provider. Our lane is the authentication, consent and audit spine underneath KYC — not the CKYC registry or the KYC decision itself. This guide is written from that boundary, so it covers the integration honestly rather than selling you a CKYC connector.

Where the rollout actually stands

Get the timing right before you plan a sprint. CKYC 2.0 (CKYCRR 2.0) was targeted for end of July 2026, with banks and insurers beginning on the upgraded framework in August 2026 and mutual funds and brokerages following later in the year as capital-markets requirements are worked through. CERSAI has published a CKYCRR 2.0 API integration and reporting-entity onboarding guide, so integration material exists.

What that does not mean is that every feature is in production for every entity type. Treat your regulator's and CERSAI's current circulars as the authority on your own go-live date, and design for the batch and real-time paths to coexist during migration. Building as though the old batch route disappears on a single date is how teams end up with an onboarding outage.

The call sequence

The order matters, because calling Download before you hold consent is both a compliance failure and a rejected request.

Customer submits an identifier (PAN / Aadhaar / DL / Voter ID)
        │
        ▼
  1. SEARCH  ──── no match ─────────────┐
        │                               │
     match(es) found                    │
        │                               │
        ▼                               ▼
  2. CONSENT + OTP                 5. COLLECT KYC
     (customer authorises              (documents, DigiLocker,
      retrieval of their record)        Aadhaar offline e-KYC)
        │                               │
        ▼                               ▼
  3. DOWNLOAD (KIN + DOB)          6. UPLOAD / GENERATE
        │                               │  → new KIN issued
        ▼                               │
  4. USE THE RECORD ◄──────────────────┘
     (your KYC decision, risk checks, storage)
        │
        ▼
  7. UPDATE when customer data changes

Two rules that are easy to miss. A search hit is not authorisation — you still need consent before retrieval. And an upload is not the end of the flow: when a customer's details change later, you owe the registry an Update, not a second Upload.

Search

Search accepts a customer identifier — PAN, Aadhaar, Driving Licence or Voter ID — and tells you whether a CKYC record already exists.

Design for three outcomes, not two:

No match. Proceed to full KYC collection and Upload. This is your new-customer path.
Exactly one match. The normal case. Move to consent, then Download.
Multiple probable matches. Do not silently pick the first result. Name and date-of-birth collisions are common at India's scale, and attaching the wrong CKYC record to a customer is a data-integrity incident that is painful to unwind. Route ambiguity to a human review queue and log the decision.

Search by Aadhaar carries the strictest handling requirements. If you can identify the customer by PAN instead, prefer it — you reduce how much Aadhaar data moves through your systems at all, which is the cheapest form of compliance.

This is the largest behavioural change in 2.0, and the step most likely to be under-scoped.

CKYC 2.0 mandates OTP-based customer consent for record retrieval. Consent is no longer a checkbox in your own UI that you record in your own database — it is a step the customer actively completes, and you must be able to evidence it afterwards.

Build it as a first-class artefact, not a boolean:

Store what was consented to (retrieval of a CKYC record), when (server timestamp), by whom (your internal customer reference), and through which channel.
Record the outcome of the OTP challenge, not just the request. A consent record that cannot distinguish "OTP sent" from "OTP verified" is not evidence.
Make it append-only. A consent record you can quietly edit later is worth nothing in an audit. This is the same reasoning behind a DPDP-grade audit trail.
Never log the OTP itself. Log that a challenge occurred and its result.

If you are already sending OTPs in India, the delivery layer has its own constraints — see phone OTP for India: DLT, cost and fallback planning, and rate-limit the endpoint, because an OTP send path without a limit is a billing attack as much as a security one.

The consent model here is closer to India's Account Aggregator consent artefact than to an OAuth scope grant: purpose-bound, time-bound, and evidenced. Do not model it as a permanent permission.

Download

Download retrieves the full record using the KIN plus the customer's date of birth. The date of birth acts as a second factor against KIN enumeration, which tells you something about how to treat the KIN: it is an identifier, not a secret, but it is also not something to expose in URLs, logs or client-side state.

When the record arrives, decide deliberately what you persist. The registry is the system of record; your database does not need to become a second copy of it. Every field you store is a field you must secure, retain, justify, and eventually delete — see authentication data retention for Indian startups for a matrix you can adapt.

Upload, Update, and why records get rejected

Rejections are the main source of pain in CKYC integrations, and almost all of them are avoidable. They come from validation, not from your HTTP client.

Guard against these before you submit:

Aadhaar not masked. Covered below. This is the one that is both a rejection and a regulatory problem.
Format drift. Dates, addresses, name fields and document codes each have expected formats. Validate against the specification locally and reject early, where you can show the customer a fixable error, instead of discovering it asynchronously.
Transliteration and name mismatch. Names arriving from different documents will not agree. Decide a canonical source and a normalisation rule, and apply it consistently.
Missing mandatory fields for the customer type. Individual, legal-entity and minor records do not require the same fields.
Update sent as Upload. Submitting a fresh record for an existing customer creates duplicates in a national registry. Search first, always.

Build a local validation layer that runs before the API call and returns field-level errors. The measurable win is that a customer fixes a problem during onboarding rather than dropping out while you reconcile a rejection queue two days later.

Aadhaar masking is not optional

CKYC 2.0 enforces Aadhaar masking on submission: the first eight digits are masked, leaving only the last four visible. This applies at the point of submission, which has an implication teams miss — masking at the boundary is not enough if the full number was already written to a log, a queue, an analytics event or a database column on the way there.

The safe pattern is to mask at ingestion and never let the full twelve digits reach persistent storage at all:

Mask as early as the value enters your system, not just before the CKYC call.
Store the last four digits, plus a hash if you need matching, plus the result of signature verification if the source was Aadhaar offline e-KYC XML.
Process the full XML in memory and discard it. Do not persist the uploaded file.
Audit your logs and error-reporting pipeline specifically. An exception handler that serialises a whole request body is the most common way a full Aadhaar number ends up somewhere it should never be.

This is the posture NamoID applies to its own Aadhaar handling, and it is worth adopting regardless of vendor: we store only the last four digits, a name hash and the signature-verification result, and the uploaded XML is processed in memory and never persisted. Aadhaar vs DigiLocker vs offline KYC compares the rails if you are still choosing one.

CKYC 2.0 also integrates DigiLocker, which is usually the better source when it fits — a DigiLocker document arrives issuer-signed and verifiable, so you inherit the verification instead of performing it. The DigiLocker API integration guide covers the consent redirect and signature check.

Getting access

You cannot call CERSAI directly because you built an integration. Access to the CKYC registry runs through entities regulated by the RBI, SEBI, IRDAI or PFRDA. If you are a fintech operating in partnership with a regulated entity, your access is derived from that relationship and is governed by it.

Plan for this to be the long pole. Onboarding as a reporting entity, obtaining credentials, completing testing in the CERSAI environment and getting production sign-off take longer than writing the client. Start that process in parallel with development rather than after it, and confirm current requirements directly with CERSAI and your regulator rather than from any secondary source, including this one.

The DPDP overlap

Almost everything CKYC 2.0 now requires — evidenced consent, purpose limitation, minimised data, masked identifiers, an audit trail — is what India's DPDP framework asks of you anyway. Build the consent record, the append-only audit log and the retention policy once, and both obligations are served by the same infrastructure.

That framing is worth carrying to your own leadership. CKYC 2.0 is not a compliance tax bolted onto onboarding; it is most of a DPDP programme, arriving with a deadline attached. The teams that treat it as one project rather than two finish considerably sooner. See DPDP access, correction and erasure for the request workflow you will also need.

Where identity fits, and where it does not

CKYC answers who this customer is, according to a registry. It does not authenticate the person in front of you, hold your sessions, issue tokens to your APIs, or record who inside your company opened a customer record.

That authentication and authorization layer is separate, and it is where NamoID sits: hosted sign-in, an OAuth 2.1-aligned OIDC issuer, scoped tokens for your internal services, session revocation, and append-only audit events covering staff access to customer data. A KYC integration without that layer leaves an obvious question unanswered during an audit — who at your company retrieved this record, and when?

Concretely, keep the boundaries separate: NamoID authenticates the customer and your staff and produces the audit trail; your CKYC integration retrieves and submits registry records; your risk engine makes the KYC decision. Conflating them produces a system nobody can reason about later.

Frequently asked questions

What are the CKYC 2.0 APIs? Four families: Search (find a record by PAN, Aadhaar, Driving Licence or Voter ID), Download (retrieve the full record using the KIN and date of birth), Upload or Generate (submit a new record and receive a KIN), and Update (amend an existing record).

Is customer consent mandatory? Yes. CKYC 2.0 mandates OTP-based customer consent for record retrieval, and you must be able to evidence it afterwards. Store it as an append-only artefact recording purpose, timestamp, channel and outcome.

How much of the Aadhaar number must be masked? The first eight digits, leaving the last four. Mask at ingestion rather than only at submission, so the full number never reaches logs or storage.

Why do CKYC uploads get rejected? Overwhelmingly validation rather than transport: unmasked Aadhaar, format drift in dates or addresses, name and transliteration mismatches, missing fields for the customer type, or an Update submitted as a new Upload. Validate locally before you call.

Can a fintech integrate with CERSAI directly? Access runs through entities regulated by the RBI, SEBI, IRDAI or PFRDA. A fintech typically integrates through its regulated partner, under that entity's governance.

When does CKYC 2.0 apply to me? Banks and insurers began on the upgraded framework from August 2026, with mutual funds and brokerages following later in 2026. Confirm your own date with your regulator and CERSAI rather than assuming a single industry-wide cutover.

Before you start building

Do these in order: confirm your access path through your regulated entity, read CERSAI's current integration guide rather than a summary, build the consent artefact and audit trail first because everything else depends on them, then write the API client. The client is the easy part.

If you are designing the authentication, consent-evidence and audit layer underneath a KYC flow, that is the part we work on — bring the design to the NamoID Slack community and we will review it with you.

NamoID is not affiliated with or endorsed by CERSAI, and does not provide CKYC registry access or make KYC decisions. CKYC 2.0 requirements, timelines and specifications change — verify every detail against CERSAI's current circulars and your regulator's guidance. This article is engineering guidance, not legal or compliance advice.

Related posts