SSO DigiLocker Suite

The new and improved SSO DigiLocker Suite of APIs enables you to easily create a dynamic DigiLocker session that is optimized to reduce user drop-offs.

❗️
DigiLocker vs SSO DigiLocker
The only major difference between the DigiLocker suite of APIs is that SSO DigiLocker APIs let you optimize the UI by enabling pinless_signin, pinless_signup and usernameless_signup.
In no way does that not mean that DigiLocker is not as good as SSO DigiLocker.
Like most things, it completely depends!
DigiLocker has a much better sign-up experience and a better hit rate, whereas SSO DigiLocker has much less friction for signing in.
Ideally, you should be using a mixture of both APIs to optimize your onboarding.

👍
Spending too much time optimizing DigiLocker flows?
Don't worry. We got you covered. Check out our orchestration API, UIStreams.
We orchestrate APIs of both DigiLocker flavors, doing all the heavy lifting, letting you focus on what matters - Your customers!

1. Initiate Session

To start the DigiLocker flow, a session has to be initiated first. A session can be initiated with Initiate Session API.

{
    "consent": true,
    "consent_purpose": "for banking purpose only",
    "reference_id": "ABCDEF12345",
    "redirect_url": "<Redirect URL for DigiLocker>",
    "redirect_to_signup": true,
    "pinless_signin": true,
    "pinless_signup": false,
    "usernameless_signup": false,
    "documents_for_consent": ["ADHAR"]
}

{
  "decentroTxnId": "DECXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "status": "SUCCESS",
  "responseCode": "S00000",
  "message": "Session created successfully.",
  "data": {
    "authorizationUrl": "<redirectUrl>"
  },
  "responseKey": "success_initiate_session"
}

{
    "consent": true,
    "consent_purpose": "for banking purpose only",
    "reference_id": "ABCDEF12345"
}

{
  "decentroTxnId": "DECXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "status": "SUCCESS",
  "responseCode": "S00000",
  "message": "Session created successfully.",
  "data": {
    "authorizationUrl": "<redirectUrl>"
  },
  "responseKey": "success_initiate_session"
}

Please refer to the master list of documents for the valid document codes for the documents_for_consent key.

😃
DigiLocker Sign Up / Sign In with Aadhaar
Yay! You can choose to redirect your customers to Aadhaar signup/login by passing an optional parameter redirect_to_signup in the request body as true.
This will take the user to Aadhaar based Sign Up and Login to DigiLocker.
By default, this parameter is false and it takes the user to Mobile Number based login screen, if not passed or false is passed.

Sign Up Flow

Sign In Flow

2. Get Issued Files

Get issued files API will fetch the list of issued documents in Digilocker.

Parameter Description

Parameter	Description
initial_decentro_transaction_id	A unique ID assigned by Decentro when the session was initiated.
consent	true/false based on if your customer has given you the consent for validating his KYC based on this. Mandatory as per regulation
consent	The purpose of taking this consent from your customer. Mandatory as per regulation
reference_id	Any unique ID assigned by you for this API request

{
    "initial_decentro_transaction_id": "DECXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "consent": true,
    "consent_purpose": "for banking purpose only",
    "reference_id": "ABCDEF12345"
}

{
  "decentroTxnId": "DECXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "status": "SUCCESS",
  "responseCode": "S00000",
  "message": "Issued files received successfully from Digilocker",
  "data": [
    {
      "name": "Aadhaar Card",
      "type": "file",
      "size": "",
      "date": "DD-MM-YYYY",
      "parent": "",
      "mime": [
        "application/pdf"
      ],
      "uri": "in.gov.uidai-XXXXXXXXXXXXXXXXXXXXXXX",
      "doctype": "ADHAR",
      "description": "Aadhaar Card",
      "issuerid": "in.gov.uidai",
      "issuer": "Aadhaar, Unique Identification Authority of India"
    }
  ],
  "responseKey": "success_issued_files"
}

3. Get e-Aadhaar

Get e-Aadhaar API will return e-Aadhaar data in XML format.

👍
Voila
Now you can get the below mentioned parameters in the response as well by passing the following params in the request body -

DigiLocker verified Aadhaar XML by passing the optional parameter generate_xml as true

eAadhaar PDF from DigiLocker verified XML by passing an optional parameter generate_pdf as true

Parameter Description

Parameter	Description
initial_decentro_transaction_id	A unique ID assigned by Decentro when the session was initiated
consent	true/false based on if your customer has given you the consent for validating his KYC based on this. Mandatory as per regulation
consent_purpose	The purpose of taking this consent from your customer. Mandatory as per regulation
reference_id	Any unique ID assigned by you for this API request
generate_xml	If you want the xml file of eAadhaar from DigiLocker
generate_pdf	If you want to generate a PDF based on DigiLocker verified eAadhaar

{
    "initial_decentro_transaction_id": "DECXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "consent": true,
    "consent_purpose": "for banking purpose only",
    "reference_id": "ABCDEF12345"
}

{
  "decentroTxnId": "DECXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "status": "SUCCESS",
  "responseCode": "S00000",
  "message": "E-Aadhaar information received successfully from Digilocker",
  "data": {
    "aadhaarReferenceNumber": "",
    "aadhaarUid": "xxxxxxxx1234",
    "proofOfIdentity": {
      "dob": "DD-MM-YYYY",
      "hashedEmail": "",
      "gender": "M",
      "hashedMobileNumber": "",
      "name": "MANISH GUPTA"
    },
    "proofOfAddress": {
      "careOf": "",
      "country": "India",
      "district": "Bengaluru",
      "house": "XXX",
      "landmark": "",
      "locality": "",
      "pincode": "XXXXXX",
      "postOffice": "",
      "state": "Karnataka",
      "street": "",
      "subDistrict": "",
      "vtc": "XXXXXXXXXXXXXXXXXXXXXXXX"
    },
    "image": "XXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "responseKey": "success_eaadhaar_download"
}

{
  "decentroTxnId": "DECXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "status": "SUCCESS",
  "responseCode": "S00000",
  "message": "E-Aadhaar information received successfully from Digilocker",
  "data": {
    "aadhaarReferenceNumber": "",
    "aadhaarUid": "xxxxxxxx1234",
    "proofOfIdentity": {
      "dob": "DD-MM-YYYY",
      "hashedEmail": "",
      "gender": "M",
      "hashedMobileNumber": "",
      "name": "MANISH GUPTA"
    },
    "proofOfAddress": {
      "careOf": "",
      "country": "India",
      "district": "Bengaluru",
      "house": "XXX",
      "landmark": "",
      "locality": "",
      "pincode": "XXXXXX",
      "postOffice": "",
      "state": "Karnataka",
      "street": "",
      "subDistrict": "",
      "vtc": "XXXXXXXXXXXXXXXXXXXXXXXX"
    },
    "image": "<Base64 of Image>",
    "xml": "<Base64 of XML File>"
  },
  "responseKey": "success_eaadhaar_download"
}

{
  "decentroTxnId": "DECXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "status": "SUCCESS",
  "responseCode": "S00000",
  "message": "E-Aadhaar information received successfully from Digilocker",
  "data": {
    "aadhaarReferenceNumber": "",
    "aadhaarUid": "xxxxxxxx1234",
    "proofOfIdentity": {
      "dob": "DD-MM-YYYY",
      "hashedEmail": "",
      "gender": "M",
      "hashedMobileNumber": "",
      "name": "MANISH GUPTA"
    },
    "proofOfAddress": {
      "careOf": "",
      "country": "India",
      "district": "Bengaluru",
      "house": "XXX",
      "landmark": "",
      "locality": "",
      "pincode": "XXXXXX",
      "postOffice": "",
      "state": "Karnataka",
      "street": "",
      "subDistrict": "",
      "vtc": "XXXXXXXXXXXXXXXXXXXXXXXX"
    },
    "image": "<Base64 of Image>",
    "pdf": "<Base64 of DigiLocker Verified eAadaar PDF File>"
  },
  "responseKey": "success_eaadhaar_download"
}

4. Download File

Download file API will download a file from Digilocker from issued documents.

Parameter Description

Parameter	Description
initial_decentro_transaction_id	A unique ID assigned by Decentro when the session was initiated.
file_urn	The uri of the file you want to dowload which can be found in Get Issued Files API
consent	true/false based on if your customer has given you the consent for validating his KYC based on this. Mandatory as per regulation
consent_purpose	The purpose of taking this consent from your customer. Mandatory as per regulation
reference_id	Any unique ID assigned by you for this API request

❗️
Important Note
This API will not download e-Aadhaar. e-Aadhaar can be downloaded only via Get e-Aadhaar API.

{
    "initial_decentro_transaction_id": "DECXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "file_urn": "in.gov.uidai-XXXXXXXXXXXXXXXXXXXXXXXXX",
    "consent": true,
    "consent_purpose": "for banking purpose only",
    "reference_id": "ABCDEF12345"
}

{
    "decentroTxnId": "DECXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "message": "File fetched successfully from Digilocker",
    "data": {
        "file": <base 64>
    },
    "responseKey": "success_file_download"
}

Other Utilities

👩🏻‍💼 Verify Phone Number

This API is a direct line to DigiLocker that checks whether a phone number has a DigiLocker account or not. Using this API, you can determine whether the user should be shown a sign-in page or a sign-up page.

{
    "consent": true,
    "purpose": "for bank account verification",
    "reference_id": "DEC001",
    "mobile": "9999999999"
}

{
    "decentroTxnId": "XXXXXXXX",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "message": "Account verified successfully.",
    "data": {
        "accountExists": true
    },
    "responseKey": "success_account_verify"
}

🏦 Get List of Issuers

This API retrieves the list of all issuers who are currently available with DigiLocker. The API also provides the organisation IDs of the issuers so that you can later fetch the document types and the related parameters in the subsequent APIs of the cycle.

{
    "consent": true,
    "purpose": "for bank account verification",
    "reference_id": "DEC001"
}

{
  "decentroTxnId": "XXXXXXXXXX",
  "status": "SUCCESS",
  "responseCode": "S00000",
  "message": "Issuers received successfully from MeriPehchaan",
  "data": {
    "issuers": [
      {
        "organisationId": "003063",
        "issuerId": "in.edu.agu",
        "name": "A P Goyal Shimla University",
        "description": "A P Goyal Shimla University is issuing their Digital awards for the following years, through DigiLocker. These can be pulled by students into their DigiLocker accounts.\n                Degree - 2014,2015,2016,2017,2018,2020,2021 \n                Marksheet - NA \n                Diploma - NA \n                Transcript - NA",
        "categories": "4,2",
        "logo": "XXXXXXXXXXXXXXXXX",
        "subdomain": "agu"
      }
    ]
  }
}

📑 Get List of Document Types

This API retrieves the list of document types available at a specific organisation ID. The API accepts the organisation ID of the issuer and returns all the documents that the organisation issues. Using these document "codes", you can pull any document from any organisation in the DigiLocker repository if your access token has the right priveleges.

{
    "consent": true,
    "purpose": "for bank account verification",
    "reference_id": "DEC001",
    "organisation_id": "XXXX"
}

{
    "decentroTxnId": "XXXX",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "message": "Document types received successfully from MeriPehchaan",
    "data": {
        "documentTypes": [
            {
                "documentType": "HLIPC",
                "description": "Insurance - Health",
                "logo": "XXXX"
            },
            {
                "documentType": "CRIPC",
                "description": "Insurance Policy - Car",
                "logo": "XXXX"
            },
            {
                "documentType": "TWIPC",
                "description": "Insurance Policy - Two Wheeler",
                "logo": "XXXX"
            }
        ]
    },
    "responseKey": "success_file_issuers_fetched"
}

🗒️ Get List of Parameters

This API is the next step in the cycle of pulling documents. Albeit hitting these APIs in this cycle is not mandatory, i.e., you can straightaway pull files if you know the organisation ID, the document type and the list of parameters, these APIs serve as a utility when fetching some documents that are not very common.

{
    "consent": true,
    "purpose": "for bank account verification",
    "reference_id": "DEC001",
    "organisation_id": "XXXX",
    "document_type": "XXXX"
}

{
    "decentroTxnId": "XXXX",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "message": "Document types received successfully from MeriPehchaan",
    "data": {
        "parameters": [
            {
                "label": "Policy Number",
                "parameterName": "policyno",
                "example": "DXXXXXXXXXXXXX/XX OR AROGXXXXXXXXXX"
            },
            {
                "label": "Phone Number",
                "parameterName": "phoneno",
                "example": "10 Digits without any prefix"
            }
        ]
    },
    "responseKey": "success_file_issuers_fetched"
}

↙️ Pull File

The Pull File API accepts the following in order to pull any document from any issuers in DigiLocker:

organisation_id: The Organisation ID of the issuer.
document_type: The document type of the specific document being pulled.
document_type_related_parameters: An array of key-value pairs that denotes all the parameters required to pull a document from the issuer.

{
    "consent": true,
    "purpose": "for bank account purpose",
    "reference_id": "XXXX",
    "organisation_id": "XXXX",
    "document_type": "XXXX",
    "document_type_related_parameters": [
        {
            "key": "Name of the key",
            "value": "Value of the key"
        },
        {
            "key": "Name of the key",
            "value": "Value of the key"
        }
    ]
}

{
  "decentroTxnId": "DXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "status": "SUCCESS",
  "responseCode": "S00000",
  "message": "Document pulled successfully from Issuer",
  "responseKey": "success_file_pull"
}

SSO DigiLocker Suite

❗️
DigiLocker vs SSO DigiLocker

👍
Spending too much time optimizing DigiLocker flows?

1. Initiate Session

😃
DigiLocker Sign Up / Sign In with Aadhaar

Sign Up Flow

Sign In Flow

2. Get Issued Files

Parameter Description

3. Get e-Aadhaar

👍
Voila

Parameter Description

4. Download File

Parameter Description

❗️
Important Note

Other Utilities

👩🏻‍💼 Verify Phone Number

🏦 Get List of Issuers

📑 Get List of Document Types

🗒️ Get List of Parameters

↙️ Pull File

❗️DigiLocker vs SSO DigiLocker

👍Spending too much time optimizing DigiLocker flows?

1. Initiate Session

😃DigiLocker Sign Up / Sign In with Aadhaar

Sign Up Flow

Sign In Flow

2. Get Issued Files

Parameter Description

3. Get e-Aadhaar

👍Voila

Parameter Description

4. Download File

Parameter Description

❗️Important Note

Other Utilities

👩🏻‍💼 Verify Phone Number

🏦 Get List of Issuers

📑 Get List of Document Types

🗒️ Get List of Parameters

↙️ Pull File

❗️
DigiLocker vs SSO DigiLocker

👍
Spending too much time optimizing DigiLocker flows?

😃
DigiLocker Sign Up / Sign In with Aadhaar

👍
Voila

❗️
Important Note