Digilocker Initialize API

Endpoint Overview

POST /api/v1/digilocker/initialize

GitHub Repository

For complete integration instructions, visit the GitHub repository.

Description

The Digilocker Initialize API is the entry point for integrating the Digiboost SDK into your Android application. This API securely provisions a session for document verification and digital identity workflows, returning a short-lived token and client ID required for SDK initialization. By leveraging this endpoint, businesses can enable seamless, secure, and customizable digital onboarding and KYC flows within their mobile apps.

Key Benefits

Rapidly enable digital document verification and eKYC in your Android app.

Fully customizable onboarding experience (branding, language, voice assistant, and more).

Secure, short-lived tokens for enhanced security and compliance.

Supports robust retry and user experience controls for high completion rates.

Use Cases

Banking & Finance

Telecom

Healthcare

- Digital onboarding for new customers with instant KYC.
- Secure loan application verification using government-issued documents.

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
Authorization	Yes	Bearer token (JWT) for API authentication
Content-Type	Yes	Must be `application/json`

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	Yes	Authentication type - must be set to "app" for SDK integration (default: 'app')
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,
    "auth_type": "app",
    "logo_url": "https://yourcompany.com/logo.png",
    "voice_assistant_lang": "hi",
    "voice_assistant": true,
    "retry_count": 3,
    "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	object	Contains session credentials for SDK initialization
data.client_id	string	Unique client identifier for the session
data.token	string	JWT token for SDK initialization (expires in 10 minutes)
data.expiry_seconds	number	Token validity duration in seconds (default: 600)
status_code	integer	HTTP status code (200 for success)
message_code	string	Status message code (`"success"` on success)
message	string	Human-readable status 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

Invalid Token

Missing Required Parameter

{
  "status_code": 401,
  "message_code": "invalid_token",
  "message": "The provided token is invalid or expired.",
  "success": false
}

The JWT token is missing, invalid, or expired. Ensure you generate a fresh token and include it in the Authorization header.

Integration Best Practices

Security Recommendations

- Always use HTTPS endpoints to protect sensitive data in transit.
- Never expose your JWT token or API credentials in client-side code or public repositories.
- Rotate your API keys and tokens regularly and monitor for unauthorized access.

User Experience Guidelines

- Customize the SDK with your brand logo and theme for a seamless user experience.
- Set appropriate retry limits to balance user convenience and security.
- Enable the voice assistant and select the preferred language to improve accessibility.
- Use skip_main_screen to streamline the onboarding flow if your UX requires it.

Code Samples

cURL

Python

Node.js

Related APIs

Digilocker Document Fetch API: Fetches user documents from Digilocker after initialization.

Digilocker Verification API: Verifies the authenticity of documents retrieved from Digilocker.

Digiboost Session Status API: Checks the status of an ongoing Digiboost session.

Compliance and Legal Considerations

Ensure user consent is obtained before initiating any KYC or document verification process.

Adhere to all applicable data privacy regulations (such as GDPR, IT Act, etc.).

Store and process user data securely; do not retain sensitive tokens or documents longer than necessary.

Digiboost Android SDK - Complete Integration Guide

Welcome to the Digiboost Android SDK Sample App! This guide will walk you through a simple 3-step journey to integrate the Digiboost Android SDK V2 into your application.

🚀 Quick Overview

The Digiboost SDK enables secure document verification and digital identity services in your Android app. Follow this guide to get up and running in minutes.

Documentation Link

Surepass.io

📋 Prerequisites

Android Studio (latest version recommended)

Minimum SDK: 26

Target SDK: 33+

Java/Kotlin support

GitHub account (for accessing SDK repository)

🎯 3-Step Integration Journey

Step 1: Generating Your SDK Token

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

1.1 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

🎥 API Tutorial Video

1.2 Environment Configuration

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

1.3 Digilocker Initialize API

For UAT Environment:

For Production Environment:

1.4 API Parameters Explanation

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	None
`voice_assistant_lang`	string	❌ Optional	Voice assistant language. Possible options: `"en"` (English), `"hi"` (Hindi)	`"en"`
`voice_assistant`	boolean	❌ Optional	Enable/disable voice assistant functionality	`false`
`retry_count`	integer	❌ Optional	Number of allowed retries during dropout prevention	`2`
`skip_main_screen`	boolean	❌ Optional	Whether to show the first intro screen or skip it	`true`

1.5 Customization Examples

Basic Configuration (Minimal):

{
  "data": {
    "signup_flow": true
  }
}

Custom Branding with Voice Assistant:

{
  "data": {
    "signup_flow": true,
    "logo_url": "https://yourcompany.com/logo.png",
    "voice_assistant_lang": "hi",
    "voice_assistant": true,
    "retry_count": 3,
    "skip_main_screen": false
  }
}

1.6 API Response

You'll receive a response like this:

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

Important:

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

The token expires in 600 seconds (10 minutes) by default

Store the client_id if needed for tracking purposes

Step 2: Creating GitHub Personal Access Token (PAT)

The Digiboost SDK is hosted on GitHub Packages. You need a Personal Access Token to access it.

🀀𐎥𘁛Generating PAT Token Video](https://github.com/surepassio/digiboost-sample-app/releases/download/1.0.0/Generating.PAT.Token.mp4)

2.1 Navigate to GitHub Settings

Go to GitHub and log in

Click your profile picture (top-right corner)

Select Settings from the dropdown menu

2.2 Access Developer Settings

Scroll down to the bottom of the left sidebar

Click Developer settings

2.3 Create Personal Access Token

Click Personal access tokens in the left sidebar

Click Tokens (classic)

Click the Generate new token button

Select Generate new token (classic)

2.4 Configure Token Settings

Note: Enter a descriptive name like "Digiboost SDK Access"

Expiration: Choose your preferred expiration (30 days, 60 days, etc.)

Scopes: Check the following permissions:

✅ read:packages (Download packages from GitHub Package Registry)

✅ repo (Full control of private repositories) - if needed

2.5 Generate and Save Token

Click Generate token at the bottom

IMPORTANT: Copy the token immediately - GitHub won't show it again!

Store it securely (you'll need it for project configuration)

2.6 Configure Your Project

Update settings.gradle:

Update build.gradle (app level):

Sync your project after making these changes.

Step 3: SDK Integration & Implementation

Now let's integrate the SDK into your application with proper initialization and response handling.

3.1 Initialize the SDK in Your Activity

3.2 Launch Digiboost SDK Activity

3.3 Handle SDK Response

🎨 Customizing SDK Theme

You can customize the SDK's appearance by modifying your app's colors.xml:

File: res/values/colors.xml

<resources>
    <color name="black">#FF000000</color>
    <color name="white">#FFFFFFFF</color>
    <color name="background_color">#B82C5A</color>
    
    <!-- Add this line to customize Digiboost SDK theme -->
    <color name="surepass_color">#FF9800</color>  <!-- Replace with your brand color -->
</resources>

After making changes:

Clean and rebuild your project

The SDK will automatically use your custom theme color

🔧 Troubleshooting

Common Issues and Solutions

Issue: "Unable to resolve dependency"

Solution:

Verify your GitHub username and PAT token in settings.gradle

Ensure your PAT token has read:packages permission

Check your internet connection

Issue: "Token expired" error

Solution:

Generate a new token using Step 1

Tokens expire after the specified time (usually 10 minutes)

Issue: "Minimum SDK version" error

Solution:

Ensure your minSdk is set to 26 or higher

Update your build.gradle accordingly

Issue: SDK not launching

Solution:

Verify the token format is correct

Check that all dependencies are properly synced

Ensure you've registered the activity result launcher before onCreate completes

This documentation provides a comprehensive, step-by-step guide for both API and SDK integration, ensuring a smooth developer experience and robust, secure onboarding for your users.
:::

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

⭐️ Initialize via Android SDK

Digilocker Initialize API#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Example Request (Webhook URL)#

Response Parameters#

Example Successful Response#

Example Webhook Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Digiboost Android SDK - Complete Integration Guide#

🚀 Quick Overview#

📋 Prerequisites#

🎯 3-Step Integration Journey#

Step 1: Generating Your SDK Token#

1.1 Get API Details from Your Sales Manager#

1.2 Environment Configuration#

1.3 Digilocker Initialize API#

1.4 API Parameters Explanation#

1.5 Customization Examples#

1.6 API Response#

Step 2: Creating GitHub Personal Access Token (PAT)#

2.1 Navigate to GitHub Settings#

2.2 Access Developer Settings#

2.3 Create Personal Access Token#

2.4 Configure Token Settings#

2.5 Generate and Save Token#

2.6 Configure Your Project#

Step 3: SDK Integration & Implementation#

3.1 Initialize the SDK in Your Activity#

3.2 Launch Digiboost SDK Activity#

3.3 Handle SDK Response#

🎨 Customizing SDK Theme#

🔧 Troubleshooting#

Common Issues and Solutions#

Issue: "Unable to resolve dependency"#

Issue: "Token expired" error#

Issue: "Minimum SDK version" error#

Issue: SDK not launching#

Request

Responses

Digilocker Initialize API

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Example Request (Webhook URL)

Response Parameters

Example Successful Response

Example Webhook Response

Possible Error Responses

Integration Best Practices

Code Samples

Digiboost Android SDK - Complete Integration Guide

🚀 Quick Overview

📋 Prerequisites

🎯 3-Step Integration Journey

Step 1: Generating Your SDK Token

1.1 Get API Details from Your Sales Manager

1.2 Environment Configuration

1.3 Digilocker Initialize API

1.4 API Parameters Explanation

1.5 Customization Examples

1.6 API Response

Step 2: Creating GitHub Personal Access Token (PAT)

2.1 Navigate to GitHub Settings

2.2 Access Developer Settings

2.3 Create Personal Access Token

2.4 Configure Token Settings

2.5 Generate and Save Token

2.6 Configure Your Project

Step 3: SDK Integration & Implementation

3.1 Initialize the SDK in Your Activity

3.2 Launch Digiboost SDK Activity

3.3 Handle SDK Response

🎨 Customizing SDK Theme

🔧 Troubleshooting

Common Issues and Solutions

Issue: "Unable to resolve dependency"

Issue: "Token expired" error

Issue: "Minimum SDK version" error

Issue: SDK not launching