DigiLocker Initialize API

Endpoint Overview

POST /api/v1/digilocker/initialize

GitHub Repository

For complete integration documentation and examples, visit the GitHub repository.

Description

The DigiLocker Initialize API is the entry point for integrating secure document verification and digital identity services through the Digiboost Web SDK. This endpoint generates authentication tokens and session configurations that enable seamless DigiLocker integration into web applications, allowing users to verify their identity using government-issued digital documents stored in their DigiLocker accounts.

The API creates a secure session with customizable parameters for user experience, notification preferences, and verification requirements, making it an essential component for KYC (Know Your Customer) and digital onboarding workflows.

Key Benefits

Instant Token Generation: Creates secure authentication tokens with configurable expiry times (5-30 minutes)

Customizable User Experience: Support for branded logos, prefilled forms, and custom styling options

Multi-Environment Support: Separate sandbox and production environments for seamless development workflow

Comprehensive Integration: Complete 3-step integration process with Web SDK for document verification

Use Cases

Financial Services

E-commerce & Marketplace

Healthcare & Education

Digital account opening and customer onboarding

KYC compliance for banking and insurance applications

Loan application processing with instant document verification

Investment platform user verification

3-Step Integration Journey

Step 1: Generating Your SDK Token

Before integrating the SDK, you need to obtain an authentication token from the DigiLocker Initialize API.

Get API Details from Your Sales Manager

Contact your sales manager to receive:

DigiLocker initialize endpoint URL

Authorization Bearer Token (required for API access)

Access permissions

Environment Configuration

We provide two environments for different stages of development:

Environment	Base URL	Usage
UAT (Testing)	`https://sandbox.surepass.app`	For development and testing
Production	`https://kyc-api.surepass.app`	For live applications

API Parameters for Token Generation

Parameter	Type	Required	Description	Default Value
`signup_flow`	boolean	✅ Required	This parameter should always be `true` for SDK initialization	`true`
`logo_url`	string	❌ Optional	Your branding logo URL - customize with your own logo	-
`skip_main_screen`	boolean	❌ Optional	Whether to show the first intro screen or skip it	`true`

Basic Configuration Example

{
    "data": {
        "signup_flow": true,
        "logo_url": "YOUR BRAND LOGO URL",
        "skip_main_screen": false
    }
}

API Response

You'll receive a response containing:

token: Authentication token for SDK initialization (expires in 600 seconds by default)

client_id: Unique identifier for tracking purposes

expiry_seconds: Token validity duration

Important: Copy the token value - you'll need this for Step 3!

Step 2: Including the SDK

The Digiboost Web SDK is available via CDN for easy integration.

CDN Integration (Recommended)

Add the SDK to your HTML page:

Sample UI Preview

The Digiboost Web SDK will render a verification button in your application. You can view the complete flow preview at: https://github.com/surepassio/surepass-digiboost-web-sdk/raw/master/assets/digilocker-flow.png

Step 3: SDK Integration & Implementation

Now integrate the SDK into your web application with proper initialization and response handling.

Basic Implementation

Advanced Implementation with Custom Styling

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Content-Type	Yes	Must be `application/json`
Authorization	Yes	Bearer token obtained from sales manager

Request Body

Parameter	Type	Required	Description
data.prefill_options	Object	No	User information to prefill in the DigiLocker form
data.prefill_options.full_name	String	No	User's full name to prefill (max 250 characters)
data.prefill_options.mobile_number	String	No	User's mobile number to prefill
data.prefill_options.user_email	String	No	User's email address to prefill
data.signup_flow	Boolean	Yes	Set to true for new users (they must provide a PIN during registration). Set to false for existing DigiLocker users (proceeds with login).
data.auth_type	String	No	Authentication type: 'web' or 'app' (default: 'web')
data.verify_phone	Boolean	No	Whether to verify user's phone number (default: false)
data.verify_email	Boolean	No	Whether to verify user's email address (default: false)
data.allow_selection	Boolean	No	Allow document selection (readonly, default: false)
data.redirect_url	String	No	URL to redirect user after DigiLocker authentication
data.webhook_url	String	No	Webhook URL for receiving verification callbacks
data.state	String	No	Custom state parameter for tracking the session (max 100 characters)
data.local_frontend_url	String	No	Local frontend URL for development purposes
data.aadhaar_xml	Boolean	No	Whether to include Aadhaar XML data (default: false)
data.send_sms	Boolean	No	Whether to send SMS notifications to user (default: false)
data.send_email	Boolean	No	Whether to send email notifications to user (default: false)
data.expiry_minutes	Integer	No	Session expiry time in minutes (min: 5, max: 30, default: 30)
data.voice_assistant	Boolean	No	Enable voice assistant feature (default: false)
data.voice_assistant_lang	String	No	Voice assistant language: 'hi', 'en', or 'both' (default: 'en')
data.retry_count	Integer	No	Number of retry attempts allowed (min: 1, max: 5, default: 1)
data.skip_main_screen	Boolean	No	Skip the main introduction screen (default: false)
data.logo_url	String	No	Custom logo URL for branding

Example Request

{
    "data": {
        "signup_flow": true,
        "logo_url": "YOUR BRAND LOGO URL",
        "skip_main_screen": false
    }
}

Example Request (Webhook URL)

{
  "data": {
    "signup_flow": true,
    "redirect_url": "https://google.com",
    "webhook_url": "https://webhook.site/a6f4fcec-5ac8-4c82-96ea-7eded59fd59a"
  }
}

Process Response

Response Parameters

Parameter	Type	Description
data.client_id	String	Unique client identifier for the session
data.token	String	JWT authentication token for SDK initialization
data.expiry_seconds	Number	Token expiry time in seconds
status_code	Integer	HTTP status code
message_code	String	Internal message code
message	String	Human-readable response message
success	Boolean	Indicates if the request was successful

Example Successful Response

{
  "data": {
    "client_id": "digilocker_cntWpMxWHbcvgghtyvxw",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiry_seconds": 600.0
  },
  "status_code": 200,
  "message_code": "success",
  "message": "Success",
  "success": true
}

Example Webhook Response

Note: This is the response sent to your webhook URL, not the API response.

{
  "client_id": "digilocker_lbsfmoudALfjHnrowLCl",
  "status": "success",
  "type": "digilocker"
}

Possible Error Responses

Authentication Error

Validation Error

{
  "status_code": 401,
  "message": "Unauthorized",
  "message_code": "auth_failed",
  "success": false
}

Invalid or missing authorization token

SDK Configuration Options

After obtaining the token from the Initialize API, configure the Web SDK with these parameters:

Parameter	Type	Required	Description
`gateway`	string	✅	Environment specification - use `"sandbox"` for testing or `"production"` for live environment
`token`	string	✅	Authentication token for the verification process
`selector`	string	❌	CSS selector where the button should be mounted (defaults to `body`)
`style`	object	❌	Custom CSS styles to apply to the button
`onSuccess`	function	❌	Callback function called on successful verification
`onFailure`	function	❌	Callback function called on verification failure or cancellation

Customizing SDK Appearance

Default Styles

Custom Styling Examples

Modern Blue Theme:

Green Success Theme:

Event Handling

Success Callback

Failure Callback

Post-Verification: Download Aadhaar XML

After completing the main Digiboost Web SDK flow, you can download the user's Aadhaar XML using a separate API endpoint:

Request Example

Response Example

{
  "data": {
    "client_id": "digilocker_CLIENT_ID",
    "digilocker_metadata": {
      "name": "John Doe",
      "gender": "M",
      "dob": "1990-01-01"
    },
    "aadhaar_xml_data": {
      "full_name": "John Doe",
      "care_of": "S/O Someone",
      "dob": "1990-01-01",
      "yob": "1990",
      "zip": "123456",
      "profile_image": "/9j/4AAQSk...",
      "gender": "M",
      "masked_aadhaar": "XXXXXXXX1234",
      "full_address": "123 Main St, City, State, Country",
      "father_name": "S/O Someone",
      "address": {
        "country": "India",
        "dist": "Some District",
        "state": "Some State",
        "po": "Some PO",
        "house": "123 Main St",
        "loc": "Some Locality",
        "vtc": "Some VTC",
        "subdist": "Some Subdist",
        "street": "Main St",
        "landmark": "Near Landmark"
      }
    },
    "xml_url": "https://aadhaar-kyc-docs.s3.amazonaws.com/.../ADHAR_XXXXXXXXXXXX.xml?..."
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Integration Best Practices

Security Recommendations

Always use HTTPS in production environments for secure token transmission

Store JWT tokens securely and avoid exposing them in client-side code

Implement proper token expiry handling and refresh mechanisms

Validate all callback data on your server before processing

User Experience Guidelines

Provide clear instructions to users about the verification process

Implement proper loading states during token generation and verification

Handle popup blockers gracefully by informing users to allow popups

Provide fallback options for users who cannot complete verification

Code Samples

cURL

Python

Node.js

Related APIs

DigiLocker Callback Handler: Processes verification results and webhooks

Aadhaar XML Download: Retrieves detailed Aadhaar information post-verification

Document Status Check: Monitors verification progress and status updates

User Session Management: Handles session tokens and expiry management

Compliance and Legal Considerations

This API handles sensitive personal identification data. Ensure compliance with:

Data Protection Laws: Follow GDPR, CCPA, and local data protection regulations

KYC Regulations: Maintain audit trails for regulatory compliance

Aadhaar Act: Comply with Indian Aadhaar data handling requirements

Storage Requirements: Implement secure storage and data retention policies

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

⭐️ Initialize via Web SDK

DigiLocker Initialize API#

Description#

Use Cases#

3-Step Integration Journey#

Get API Details from Your Sales Manager#

Environment Configuration#

API Parameters for Token Generation#

Basic Configuration Example#

API Response#

CDN Integration (Recommended)#

Sample UI Preview#

Basic Implementation#

Advanced Implementation with Custom Styling#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Example Request (Webhook URL)#

Response Parameters#

Example Successful Response#

Example Webhook Response#

Possible Error Responses#

SDK Configuration Options#

Customizing SDK Appearance#

Default Styles#

Custom Styling Examples#

Event Handling#

Success Callback#

Failure Callback#

Post-Verification: Download Aadhaar XML#

Request Example#

Response Example#

Integration Best Practices#

Code Samples#

Request

Responses