—
–
/

to search

Introducing Setu Changelog Check it out ↗

Reading time — 19 minutes

Edit this page ↗

#DigiLocker integration

Setu DigiLocker APIs can be used to fetch documents of your users instantly—with their consent.

Here’s a quick run through of the APIs—

  • Create a DigiLocker request—Create a request to start the user journey, with which you can get user consent and then fetch the document from user’s digilocker. You get an id in response, which you can use to track this request throughout the journey.
  • Get DigiLocker request status—Check status of a request that was created by passing the request id, at any point in the journey.
  • Get list of all docs available—Get a global list of all documents that DigiLocker lets you fetch and the identifiers required to fetch a particular document.
  • Fetch a document—Get the document that the user has consented to share with you, made available as a file URL to download. All docs other than Aadhaar, can be fetched with this API.
  • Fetch Aadhaar data—Fetch Aadhaar document data in JSON format as well as an XML file. The API response is consistent with our OKYC APIs, which aids in replacing OKYC with DigiLocker, for carrying out Aadhaar KYC.
  • Revoke access token—Revoke the OAuth user token, once necessary user documents are fetched.

Additionally, here are the URLs you would need for these APIs—

  • Sandbox—https://dg-sandbox.setu.co
  • Production—https://dg.setu.co
  • Headers—Contact Setu for providing the credentials required to successfully call Setu APIs. This contains:
    • x-client-id
    • x-client-secret
    • x-product-instance-id

#Create a DigiLocker request

Call this API to create a new DigiLocker request. Pass the redirectUrl in the request body.

A DigiLocker account is not mandatory for a user to start this flow. If the user does not have a DigiLocker account, DigiLocker will automatically create an account during the consent journey. User has to sign up by providing their Aadhaar number and authenticate with the OTP sent to Aadhaar registered mobile number.


To sign up for DigiLocker, user should have linked their mobile number with Aadhaar.


Usage of the redirect URL

You have to provide a redirectUrl in the request, which has to be a valid publicly hosted URL—the user gets redirected to this URL after going through DigiLocker Sign in / Sign up and consent screens.

It will also be used by Setu to send back relevant information about a request. By default Setu includes the success flag of the user consent and DigiLocker request id.

It also includes a scope parameter, which provides the information about the documents the user has consented to during their UI journey. The possible values are ADHAR for Aadhar, PANCR for PAN and DRVLC for Driver's License.


Consent state Redirect URL
Failed user consent <redirectUrl>?success={False}&id={Digilocker_request.id}&errCode={code}&errMessage={message}
User Consent to Aadhaar <redirectUrl>?success={True}&id=Digilocker_request.id&scope=ADHAR
User consent to all three documents <redirectUrl>?success={True}&id=Digilocker_request.id&scope=ADHAR%2BPANCR%2BDRVLC
User journey completed without selecting any document <redirectUrl>?success={True}&id=Digilocker_request.id&scope=

You can also add custom query params such as session id from your end. You would append this to the provided URL, like so—(redirectUrl)?sessionId=XYZ

Setu has processed your request successfully.

Request
POST /api/digilocker/ 
 
{ 
    "redirectUrl": "https://setu.co" 
}
Response

You will get the following details—

  • Unique DigiLocker request id which can be used to manage this request.
  • The status will be unauthenticated for requests that do not have user consent yet and will change to authenticated once the user has provided their consent. You can check the status of a request at any point of time, using the Get DigiLocker request status API.
  • The url from the response should be used to redirect your user to Sign in / Sign up and provide consent to access their DigiLocker.
  • Validity of this request in ISO 8601 format timestamp, after which the request is expired and deleted.
{ 
    "id": "ea31e1e6-96eb-4e56-a355-7bc51de94d24", 
    "status": "unauthenticated", //ENUM values—unauthenticated | authenticated | revoked 
    "url": "User login url", 
    "validUpto": "2021-10-05T19:06:28+05:30"  
}

#Get DigiLocker request status

Call this API to get status of a DigiLocker request.

Setu has processed your request successfully.

Request

Pass the DigiLocker request id as a URL parameter

GET /api/digilocker/:id/status
Response

You will get the following details—

  • DigiLocker request id

  • The status will be unauthenticated for requests that do not have user consent yet and will change to authenticated once the user has provided their consent.

  • The url from the response should be used to redirect your user to Sign in / Sign up and provide consent to access their DigiLocker.

  • Validity of this request in ISO 8601 format timestamp, after which the request is expired and deleted.

  • digilockerUserDetails, for the DigiLocker user associated with this request. If the request is not authenticated, this will be an empty dictionary. In case the request is authenticated, this field will contain the following details (if available from DigiLocker):

    • digilockerId - The DigiLocker ID of the user
    • email - The email of the user
    • phoneNumber - The phone number of the user

  • A traceId for this request, which you can share with us for debugging purposes.

{ 
    "id": "477dc21a-fa28-4c7f-9291-f35d63d5bda7", 
    "status": "authenticated", //ENUM values—unauthenticated | authenticated | revoked 
    "url": "User login url", 
    "validUpto": "2021-10-06T08:43:18+05:30",
    "digilockerUserDetails": {
        "digilockerId": "DL-8de97146-e7f0-5b80-a3b2-0f01nd6c14ad",
        "email": "abc@gmail.com",
        "phoneNumber": "1234567899"
    },
    "traceId": "1-65f9b08c-0f4644093941c9dd0f9fd5cc"
}

#Get list of all docs available

Call this API to get a global list of all documents that DigiLocker lets you fetch and the corresponding meta data for each document.

This list can be very huge and the response can take a few minutes. It is recommended that you store this list on your end for usage in your application.


Consider updating this list of documents only once every month or as needed, as it does not change very often.

Setu has processed your request successfully.

Request
GET /api/digilocker/documents
Response

Each document in the response has the following details—

  • availableFormats is an array that specifies the formats in which the document is made available through DigiLocker.
  • description specifies the name of the document, as given by the document issuer.
  • docType is a short code that identifies the type of the document.
  • orgId is the code of the document issuer.
  • orgName is the name of the document issuer

To uniquely identify a document, both docType and orgId are necessary. Multiple issuers, with their unique orgId, can issue documents which can be of the same docType. A quick example would be driving license being issued by different states—the docType is same whereas the orgId differs.

  • parameters is an array that contains key-value pairs, which specifies the user-specific identifiers required to fetch the document. You can use the description to aid your user, to input information on your UI.

A document can require more than one parameter, as specified by the document issuer.


description key-value pair in parameters array, is only for your information and should not to be passed as an identifier to fetch that document


{ 
    "documents": [ 
        { 
            "availableFormats": [ 
                "pdf" 
            ], 
            "description": "Pension Certificate", 
            "docType": "PECER", 
            "orgId": "002317", 
            "orgName": "Accountants General, Tripura", 
            "parameters": [ 
                { 
                    "description": "Account No./PPO No.", 
                    "name": "AC_NO" 
                } 
            ] 
        }, 
        { 
            "availableFormats": [ 
                "pdf" 
            ], 
            "description": "Provident Fund Member Passbook", 
            "docType": "PRFND", 
            "orgId": "002317", 
            "orgName": "Accountants General, Tripura", 
            "parameters": [ 
                { 
                    "description": "Account No./PPO No.", 
                    "name": "AC_NO" 
                }, 
                { 
                    "description": "Name of the member", 
                    "name": "MemberName" 
                } 
            ] 
        } 
    ] 
}

#Fetch a document

Call this API to fetch document of a user from DigiLocker.

Setu has processed your request successfully and the document was fetched.

Request

Provide the following details in the request—

  • DigiLocker request id as a URL parameter
  • Refer to the response of Get list of all docs available API for obtaining document specific values explained here—
    • docType of the document
    • orgId of the document issuer
    • The format in which you require the document. This should be one of the formats that the document is actually available in.
    • User consent should be Y to attempt a document fetch
    • parameters is an array that contains key-value pairs, which specifies the identifiers required to fetch the document. Refer to the sample response of Get list of all docs available API for a detailed explanation of parameters array.

Note that for each parameter specified by the document issuer—

The first element has to be the key-value pair specified by the document issuer, like so— "name": "MemberName".
The second element should be the key-value pair with the actual value of the parameter specified, like so— "value":"Ramesh".


POST /api/digilocker/:id/document 
 
{ 
    "docType": "PRFND", 
    "orgId": "002317", 
    "format": "pdf", 
    "consent": "Y", 
    "parameters": [ { 
        "name": "AC_NO", 
        "value": "98432234234" 
    }, 
    { 
        "name": "MemberName", 
        "value": "Ramesh" 
    }] 
}
Response

You will get the following details—

  • fileUrl to download fetched document

  • Validity of the fileUrl in ISO 8601 format timestamp

{ 
    "fileUrl": "s3_url of the file to be downloaded", 
    "validUpto": "2021-09-21T09:12:12+05:30" 
}

#Fetch Aadhaar data

Call this API to fetch the Aadhaar data of a user from DigiLocker. The Aadhaar XML file is signed by DigiLocker.

Setu has processed your request successfully and Aadhaar data was fetched successfully.

Request

Provide the DigiLocker request id in the request—

GET /api/digilocker/:id/aadhaar
Response

You will get the Aadhaar data of the user as JSON along with thefileUrl to Aadhaar XML.

The shareCode will always be empty for this API and is present to match the JSON response of Setu OKYC APIs.


{
    "aadhaar": { 
        "address": { 
            "careOf": "S/O John Doe", 
            "country": "India", 
            "district": "district", 
            "house": "house address", 
            "landmark": "", 
            "locality": "locality", 
            "pin": "123456", 
            "postOffice": "", 
            "state": "state", 
            "street": "", 
            "subDistrict": "", 
            "vtc": "vtc" 
        }, 
        "dateOfBirth": "01-01-1990", 
        "email": "", 
        "gender": "M", 
        "generatedAt": "2021-10-26T17:17:36.342+05:30", 
        "maskedNumber": "xxxx-xxxx-1234", 
        "name": "Jack Doe", 
        "phone": "", 
        "photo": "", 
        "verified": { 
            "email": false, 
            "phone": false, 
            "signature": true 
        }, 
        "xml": { 
            "fileUrl": "https://s3linkgoeshere.com", 
            "shareCode": "", 
            "validUntil": "2021-10-09T06:04:16+05:30" 
        } 
    }, 
    "id": "391a45be-d08d-4dd0-b8a8-06e53392d435", 
    "status": "complete" 
}

#Revoke DigiLocker request

Call this API to revoke a DigiLocker request. The request id can no longer be used to interact with user’s DigiLocker.

Setu has processed your request successfully.

Request

Provide the DigiLocker request id in the request—

GET /api/digilocker/:id/revoke
Response
{ 
    "success": true 
}

Was this page helpful?