---
title: "Start DigiLocker session"
method: POST
path: "/v1/kyc/digilocker/session"
tags: ["KYC"]
---

# Start DigiLocker session

`POST /v1/kyc/digilocker/session`

Start a DigiLocker session to fetch the investor's government-issued
documents (Aadhaar, PAN, etc.) with their consent.

**How it works:**
1. Call this endpoint — you get back an `authorization_url` and a
   `session_id`. The `session_id` is the single identifier you use
   for everything else.
2. Redirect the investor to `authorization_url` to log in to DigiLocker
   and grant consent.
3. After consent, the investor is redirected back to your `redirect_url`
   with query parameters appended (see the table below).
4. Use the `session_id` (path parameter) on the
   `POST /v1/kyc/digilocker/result/{session_id}` endpoint to read the
   consented data — identity, documents, and parsed document content.

**Redirect parameters appended to your `redirect_url`:**

| Outcome | Appended query parameters |
| --- | --- |
| Consent granted | `?success=true&id={session_id}&state={state}&documents=pan+driving_licence&has_verified_data=1` |
| Partial consent (e.g. PAN only) | `?success=true&id={session_id}&state={state}&documents=pan` |
| Consent denied / failed | `?success=false&id={session_id}&state={state}&error={error}` |

`documents` lists the documents the investor agreed to share;
`has_verified_data=1` appears only when verified identity is available.

**Credits:** Free. Billing happens when documents/identity are returned.

## Request body

- object
  - `consent` boolean, required — Explicit end-user consent. Must be `true` to proceed (regulatory requirement under DPDP / RBI). Captured for audit.
  - `consent_purpose` string, required — Specific purpose for which consent is taken (min 20 chars). Stored in the session and returned as a consent receipt.
  - `documents` string[] — Identities to verify and return in the response.
  - `prefill_mobile` string — Pre-verified mobile to skip the signup OTP step (only applies with user_flow=signup).
  - `redirect_url` string, uri, required — Where to redirect the user after consent. Must be a valid http/https URL.
  - `state` string — Opaque value echoed back to your redirect_url unchanged.
  - `user_flow` 'signin' | 'signup' — Use "signin" for users with an existing DigiLocker account, "signup" for account-on-the-fly.

## Response `200`

Session started; redirect the user to authorization_url

- object
  - `authorization_url` string — DigiLocker consent URL to redirect the investor to.
  - `expires_in` integer — Seconds the authorization_url is valid for.
  - `session_id` string — The single identifier for this verification. Use it as the path parameter in `POST /v1/kyc/digilocker/result/{session_id}` to retrieve identity + documents.
  - `status` string

## Other responses

- `400` — Validation error. `code` indicates which: `consent_required` (consent not true), `consent_purpose_required` (missing/too short), or `redirect_url_invalid`.
- `401` — Unauthorized. This can happen if the `x-api-key` header is missing.
- `503` — DigiLocker is temporarily unavailable

---

[API](https://skmtc.net/casparser/apis/cas-parser-track-portfolios-from-cdsl-nsdl-cams-kfintech.md) · [All operations](https://skmtc.net/casparser/apis/cas-parser-track-portfolios-from-cdsl-nsdl-cams-kfintech/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/casparser/cas-parser-track-portfolios-from-cdsl-nsdl-cams-kfintech/revisions/fa7d3aae2ab9/schema)