> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privue.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# DigiLocker

> Retrieve a user's government-issued documents after they grant consent.

DigiLocker is a redirect flow. The user signs in to DigiLocker, consents to sharing the documents you
asked for, and returns to your application. Documents can only be read after consent completes.

<Steps>
  <Step title="Check whether they have an account (optional)">
    `POST /digilocker-simple/v1/user/verify` with an Aadhaar number or a mobile reports whether a
    DigiLocker account exists, so you can route the user to sign-in or sign-up.
  </Step>

  <Step title="Initiate a session">
    `POST /digilocker-simple/v1/sessions` with the documents you need and an HTTPS `redirect_url`.
    Returns a `session_id` and an `authorization_url`.
  </Step>

  <Step title="Send the user to DigiLocker">
    Redirect them to `authorization_url`. They authenticate and grant consent on DigiLocker's own
    screens, and are returned to your `redirect_url`.
  </Step>

  <Step title="Wait for consent">
    Poll `GET /digilocker-simple/v1/sessions/{session_id}/status` until `status` is `succeeded`.
    Polling is free.
  </Step>

  <Step title="Read what they shared">
    `GET /digilocker-simple/v1/sessions/{session_id}/documents/{doc_type}` returns the issued files.
    `GET /digilocker-simple/v1/sessions/{session_id}/user/profile` returns the account holder's
    details.
  </Step>
</Steps>

## Session states

`status` is `created` from the moment the session is initiated until the user finishes granting
consent, and `succeeded` once they have.

Reading a profile or a document before then returns `409`. Poll the status and retry.

The `authorization_url` is single use. If a user abandons the flow, initiate a new session rather
than reusing the URL.

## Documents

A document is returned as the files DigiLocker issued for it:

```json theme={null}
{
  "code": 200,
  "timestamp": 1751975529441,
  "transaction_id": "a4d43b74-0f9c-480c-9300-f011100b674b",
  "data": {
    "files": [
      {
        "url": "https://.../in.gov.uidai-ADHAR-0d5fe4d6.xml?X-Amz-Expires=3600",
        "size": 16598,
        "metadata": {
          "content_type": "application/xml",
          "last_modified": "09/05/2025",
          "issuer_id": "in.gov.uidai",
          "issuer": "Unique Identification Authority of India (UIDAI)",
          "description": "Aadhaar Card"
        }
      }
    ]
  }
}
```

<Warning>
  Each `url` expires about an hour after it is issued. Download the file when you receive the
  response and store it yourself. We do not keep a copy.
</Warning>

Files are the issuer's own signed documents, byte for byte, so a signature check on one still
verifies. Aadhaar and PAN arrive as signed XML, from which the holder's details can be read.

## Choosing document types

`doc_types` accepts `aadhaar`, `pan` and `driving_license`. Each requested type appears on the
user's consent screen, so request only what you need.

The `doc_type` you fetch must be one the user consented to. Any other type returns `404` until you
open a new session that includes it.