Requester Specification

Version 2.1

October 2016

A Digital India Initiative

National e-Governance Division.
Ministry of Electronics and Information Technology.
 Requester Specification

Revision History
Version Date Comments
1.0 12/08/2015 Version 1.0 Released.
1.1 16/06/2016 Added support for a smaller Fetch from Locker button.
2.0 25/07/2016 The new version supports file sharing through an API using
the document URI. The URL based file sharing will be
deprecated.
2.1 05/10/2016 Added sharedTill parameter in the JSON data about the
shard document.

1
 Requester Specification

Table of Contents
Revision History....................................................................................................................................................... 1
Introduction............................................................................................................................................................... 3
Sample Requester Workflow .............................................................................................................................. 3
Step 1: User clicks “Fetch from DigiLocker” button on the requestor application. .................. 3
Step 2: DigiLocker Requestor Widget pops up and prompts user to login. ................................ 4
Step 3: User logs in to the account and selects a file to share. .......................................................... 4
Step 4: DigiLocker shares file with the client application and shows status message............ 5
Steps to Integrate As a Requester ..................................................................................................................... 5
Step 1: Register as Requestor on DigiLocker........................................................................................... 5
Step 2: Register Requestor Application and Domain on DigiLocker .............................................. 6
Step 3: Integrate DigiLocker Requestor Widget in your web application ................................... 6
Step 4: Handling the Response from the Widget ................................................................................... 8
Step 5: Fetching the File from DigiLocker .............................................................................................. 10

2
 Requester Specification

Digital Locker Requester Specification

Introduction
This document provides technical details required to integrate with Digital Locker as a
Requester. Digital Locker Requestors are organizations that can access users’ documents
from their Digital Locker. This document assumes that the reader is aware of Digital Locker
application functionality.

Sample Requester Workflow

Digital Locker Requestor workflow is a combination of web flow and supporting API. Digital
Locker provides a “Fetch from DigiLocker” button which can be integrated with the
requester’s web application. An end user using the requester’s web application can click on
this button to share a document from his/her Digital Locker with the requester’s web
application. The user is asked to login to his/her Digital Locker account in a pop up window.
Once the user is logged in to his/her account, the user sees the contents of his/her account
from Issued and Uploaded documents in different tabs. The user can select the document
and click share button. At this point Digital Locker shared the details of the document with
the requester application. The requestor application then can call the API provided by
Digital Locker to get the actual document using the details provided. The user must have
signed up for Digital Locker before he can share the documents this way. The requestor
workflow steps are as follows

Step 1: User clicks “Fetch from DigiLocker” button on the requestor

application.

3
 Requester Specification

Step 2: DigiLocker Requestor Widget pops up and prompts user to login.

Step 3: User logs in to the account and selects a file to share.

4
 Requester Specification

Step 4: DigiLocker shares file with the client application and shows status
message.

Steps to Integrate As a Requester

Following steps provide technical details to integrate your application with Digital Locker
as a Requester.

Step 1: Register as Requestor on DigiLocker

The first step in integrating with Digital Locker application is to register your organization
on Digital Locker as a Requester. You can visit https://partners.digitallocker.gov.in/ for
registering your organization on Digital Locker on production environment.

5
 Requester Specification

Step 2: Register Requestor Application and Domain on DigiLocker

On successful registration, the Requester application must be registered along with the
domain of your application from which the requests to Digital Locker will be initiated.
During the registration process you create an application id (app id) for your application.
You are provided with an API key which is a secret key. The App Id and the API key are used
to authenticate the request from your application. You can also select whether you want to
receive only issued document or only self uploaded documents or both from DigiLocker.
Based on this configuration, a user only sees Issued Documents section or Uploaded
Documents Section when he/she logs in to DigiLocker for document sharing.

Step 3: Integrate DigiLocker Requestor Widget in your web application

6
 Requester Specification

DigiLocker provides a Requestor Widget to share files from DigiLocker. This widget can be
launched with a button provided by DigiLocker Javascript library. The button launches
DigiLocker application login page in a popup. A user can login to his/her DigiLocker account
to select a file that the user want to share with the requestor application. This button looks
like this -

Once you register as a Requester and register your application with Digital Locker, add
following JavaScript snippet to your web page.

<script src="jquery.min.js"></script>

<script type="text/javascript"
src="https://services.digitallocker.gov.in/requester/api/2/dl.js"
id="dlshare" data-app-id="YOUR_APP_ID" data-app-hash="YOUR_APP_HASH"
time-stamp=”TIMESTAMP” data-callback="YOUR_FUNCTION_NAME">
</script>

Please note that the DigiLocker library uses jQuery. So please download jquery.min.js file
from jQuery.com and place it on your web server. Specify the path of this file in the above
snippet in the src parameter of jQuery script.

The next script element refers to the DigiLocker JavaScript library and your DigiLocker
application credentials. The src parameter denotes the path of the DigiLocker JavaScript
library. The paths for development and production environments are as follows:
Development: https://devservices.digitallocker.gov.in/requester/api/2/dl.js
Production: https://services.digitallocker.gov.in/requester/api/2/dl.js

Provide app id that was provided during the application registration process in data-app-
id parameter.

Provide SHA-256 encrypted value of your app id, app key and the timestamp values in this
sequence in data-app-hash parameter.

Provide a timestamp value in UNIX (or POSIX) format in IST time zone in seconds in time-
stamp parameter. This timestamp value must not be older than 30 minutes.

DigiLocker JavaScript library returns the URI of the file shared by the user and its metadata
to your application by calling a JavaScript callback function in your web application. Provide
the name of this callback JavaScript function in data-callback parameter. Please refer to
‘Handling The Response’ section below for more details.

To add the “Fetch from DigiLocker” button to your page, add following line to your web
page where you want to add the button. Provide a unique id for every instance of the
button on your web page. The value of id can be used to identify the type of document
being shared by a user.

7
 Requester Specification

<div class="share_fm_dl" id="attachment_poi"></div>

A smaller “Fetch from DigiLocker” button is also available if you prefer a smaller size of the
button that suits your website. The smaller button looks like this –

To add the smaller button to your page, add following line to your web page where you
want to add the button. Please note that you need to use share_fm_dl_sm class for this
button.

<div class="share_fm_dl_sm" id="attachment_poi"></div>

If the integration is successful, the DigiLocker Requestor Widget will be launched and you
will see the DigiLocker login page. If there is an error in the integration, the widget will
show an authentication error and an error code. Following table lists the error codes.

Code Description
203 Invalid app hash. One of app id, app key or timestamp is incorrect.
204 Invalid app id.
205 The app domain is not registered.
206 The timestamp is older than 30 minutes.
207 Not authorized for service.

Step 4: Handling the Response from the Widget

DigiLocker workflow returns the URI and the metadata of the shared document in JSON
format. DigiLocker library calls the callback function provided by you in data-callback
parameter with the JSON data as a parameter string. The callback function should process
the JSON data and store the URI and the metadata. The client application must retrieve the
document from this URI using an API provided by DigiLocker and save it at a secure
location.
DESCRIPTION
This service will be provided by the client application over https.

CALLBACK FUNCTION DEINITION

function myCallback(arg) {
//arg contains the file metadata in JSON format.
//Store this data as per your application requirements.

return “SUCCESS”; // or “FAILURE”

}

8
 Requester Specification

ARGUMENT FORMAT
The argument to the call back function will be in following format -

{
"docId" :”attachment_poi”,
"uri" :"in.gov.digilocker-OTHER-39491058586222",
"docType" :"Income Certificate",
"source" :"U",
"txn" :"11396059763949",
"filename" :"PANCARD.pdf",
"contentType" :"application/pdf",
"sharedTill" :"31-03-1980"
}

ARGUMENT DETAILS
 docId This is the id value of the “Fetch from DigiLocker” button. This can be
associated with the type of document the user is uploading such as proof of identity
(PoI) or proof of address (PoA). This element is helpful if your web page contains
more than one “Fetch from DigiLocker” buttons.
 uri This is the unique identifier of the document shared by the user in
DigiLocker. You will use this identifier to get the actual file from DigiLocker using
the API.
 docType This is the descriptive document type stored in DigiLocker such as
‘Income Certificate’ or ‘Driving License’.
 source This indicates whether the document is shared from the self uploaded
documents section (“U”) or the issued documents (“I”) section of the DigiLocker.
Issued documents are shared from the issuers’ repository and are the most
authentic documents.
 txn This is the unique transaction number for this sharing activity. You will need
to pass this to DigiLocker API while fetching the file.
 filename This is the name of the file shared by user as in DigiLocker if it is shared
from uploaded documents section. If the file is shared from issued documents
section then the filename contains the URI.
 contentType This denotes the file type. This field will contain “application/PDF” for
PDF files; “image/png” for PNG files and “image/jpg” or “image/jpeg” for JPG/JPEG
files.
 sharedTill This is the date till which the user has shared the file with the
Requestor. The date is in DD-MM-YYYY format. The Requestor cannot access this file
after this date. An empty string in this parameter means the shared file is available
permanently.
RETURN
The callback function should return ‘SUCCESS’ if the data is successfully stored or
‘FAILURE’ in case of failure. DigiLocker library displays the success or failure details
to the user based on this return value.

9
 Requester Specification

Step 5: Fetching the File from DigiLocker

DigiLocker provides a REST API to fetch the file using the URI. The details of this API are as
follows:
API END POINT
Development Environment-
https://devpartners.digitallocker.gov.in/public/requestor/api/pulldoc/1/xml
Production Environment-
https://partners.digitallocker.gov.in/public/requestor/api/pulldoc/1/xml

METHOD POST

HEADER
Name: Content-Type
Value: application/xml
XML REQUEST STRUCTURE

<?xml version=”1.0” encoding=”utf-8” standalone=”yes”?>

<PullDocRequest xmlns:ns2=”http://tempuri.org/” ver=”1.0” ts=”YYYY-MM-
DDThh:mm:ss+/-nn:nn” txn=”” orgId=”” appId=”” keyhash=”sha256(key+ts)”>
<DocDetails>
<URI>in.gov.digilocker-OTHER-1234567890</URI>
</DocDetails>
</PullDocRequest>

Various elements/attributes in the request are described below-

Sr. XML Element Mandatory (M)/ Description

No. Optional (O)
1. ver M API version.
2. ts M A timestamp value. This will be
used to decode the keyHash
element described below.
3. txn M A unique transaction id provided
by DigiLocker application as
document metadata.
4. orgId M Org Id is the issuer id provided to
the issuer portal by Digital Locker
application.
5. appId M The requestor application id as
registered in DigiLocker issuer
portal.
6. keyhash M Provide SHA-256 encrypted value
of the API key and the timestamp
values concatenated together in
this sequence.
7. URI M URI of the document to be

10
 Requester Specification

fetched.

XML RESPONE STRUCTURE

The response to the above request will include the Base64 encoded document content
wrapped in a XML envelope. DigiLocker will return a PDF, JPG or PNG file.

The following is the XML response template for the Response API.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<PullDocResponse xmlns:ns2="http://tempuri.org/" ts=”YYYY-MM-
DDThh:mm:ss” txn="">
<ResponseStatus>//Error Code </ResponseStatus>
<DocDetails>
<DocContent contentType=””>
//Bytes encoded with Base64 in string format
</DocContent>
</DocDetails>
</PullDocResponse>

Various elements/attributes in the response are described below-

Sr. XML Element Mandatory (M)/ Description

No. Optional (O)
1. ts M A timestamp value as sent in the
request.
2. txn M Transaction id as passed in the
request.
3. ResponseStatus M Refer to the table below for the
possible response codes.
4. DocDetails M Envelope for document content.
5. DocContent M Enclose the Base64 byte encoded
contents of PDF, JPG or PNG file
in this element.
6. contentType M Provides the MIME type of the
document within DocContent. It
contains:
“application/PDF” for PDF files;
“image/png” for PNG files and
“image/jpg” or “image/jpeg” for
JPG/JPEG files.

The possible values for the ResponseStatus element are listed below-

Code Description
1 Success. The document data will be available in DocContent element in this
case.

11
Requester Specification

203 Invalid app hash. One of app id, app key or timestamp is incorrect.
204 Unauthorized access. Invalid URI or transaction id (txn).
205 Unauthorized access. The document is not shared with the requestor. One of
URI, transaction id (txn) or orgId is incorrect.
0 Undefined technical error.

12