Create URL

14 min

Introduction

This is the first API call to be made. Create URL responds with a url and a request ID. One can open this url in the browser for end user authentication. On this page, the end user enters the Aadhaar number, captcha, OTP received on the linked mobile number and the PIN to authorize his/her Digilocker account to pull details.

Steps to get URL

Open Digilocker iFrame
Enter Aadhaar number
Verify with the OTP sent on the registered mobile number
Load Digilocker Url
- Open the URL in a web browser.
- In the case of a web app product, load the URL in the iframe
- In the case of mobile APP, load the URL in the web view and you need to enable local storage in our APP.
- Once URL is open, you have to enter your Digilocker credentials and give consent that Signzy can download the file on the client behalf
- Once Signzy is authorized, a thank you page will be shown

Once access is granted, RequestID can be then used further to call API's like, Get Aadhaar details, Get details of issued docs etc.

How to call the API

You will need to log in before sending the request. You are required to pass the access token received from the login call, as the authorization header in the request.

API Input Guidelines

Need to pass follow information

Sample Curl

Preproduction

Production

curl --location --request POST 'https://api-preproduction.signzy.app/api/v3/digilocker/createUrl' \
--header 'Authorization: <auth-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "signup" : <true/false>,
    "redirectUrl" : "...redirectUrl...",
    "redirectTime" : "...redirectTime...",
    "callbackUrl" : "...callbackUrl...",
    "customerId" : "...customerId...",
    "successRedirectUrl" : "...successRedirectUrl...",
    "successRedirectTime" : "...successRedirectTime...",
    "failureRedirectUrl" : "...failureRedirectUrl...",
    "failureRedirectTime" : "...failureRedirectTime...",
    "logoVisible":true,
    "logo":"https://images.indianexpress.com/2021/01/myntra.png",
    "supportUrlVisible":true,
    "supportUrl":"www.google.com"
}'

curl --location --request POST 'https://api.signzy.app/api/v3/digilocker/createUrl' \
--header 'Authorization: <auth-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "signup" : <true/false>,
    "redirectUrl" : "...redirectUrl...",
    "redirectTime" : "...redirectTime...",
    "callbackUrl" : "...callbackUrl...",
    "customerId" : "...customerId...",
    "successRedirectUrl" : "...successRedirectUrl...",
    "successRedirectTime" : "...successRedirectTime...",
    "failureRedirectUrl" : "...failureRedirectUrl...",
    "failureRedirectTime" : "...failureRedirectTime...",
    "logoVisible":"true",
    "logo":"https://images.indianexpress.com/2021/01/myntra.png",
    "supportUrlVisible":"true",
    "supportUrl":"www.google.com"
}'

Input Parameters

FIELD	DESCRIPTION	TYPE	REQUIRED
signup	true/false(default: false; to be sent as true, if a new user is to be signed up at Digilocker),	Boolean	optional
redirectUrl	URL enduser will be redirected to after journey is done	String	optional
redirectTime	(default 10s if redirectUrl is provided)	String	optional
callbackUrl	callbackUrl to which data will be posted once digilocker account is authorized	String	optional
customerId	(patronId - if passed custom digilocker clientId will be used instead of default signzy clientId)	String	optional
successRedirectUrl	if passed - redirection will be done on the same in case of success, else redirectUrl will be used	String	optional
successRedirectTime	if passed - success redirection will be done after the successRedirectTime is elapsed other wise redirectTime will be used, if redirectTime is missing default to 10 seconds	String	optional
failureRedirectUrl	if passed - redirection will be done on the same in case of failure, else redirectUrl will be used	String	optional
failureRedirectTime	if passed - success redirection will be done after the failureRedirectTime is elapsed other wise redirectTime will be used, if redirectTime is missing default to 10 seconds.	String	optional
logoVisible	true/false(if set to true, custom logo will be visible in digilocker success/error page).	Boolean	optional
logo	url of the logo which needs to be passed if logoVisible is set to be true	String	optional
supportUrlVisible	true/false(if set to true, custom support url wil be visible in digilocker success/error page).	Boolean	optional
supportUrl	url of support which needs to be passed if supportUrlVisible is set to be true.	String	optional

Sample Response

{
    "result": {
        "url": "<URL>",
        "requestId": "<request id>"
    }
}

Response Parameter

FIELD	DESCRIPTION	TYPE
result	Contains content of response	String
requestId	..request Id..	String
url	URL to be loaded in iframe	String

Sample Response posted to callback

1) Success Scenario

    {
        "event": "consentComplete",
        "requestId": "",
        "message": "",
        "status": "success",
        "timestamp": ,
        "aadharDetail": {
          "name": "",
          "uid": "",
          "dob": "",
          "gender": "MALE",
          "x509Data": {
            "subjectName": "",
            "certificate": "",
            "details": {
              "version": 2,
              "subject": {
                "countryName": "IN",
                "organizationName": "",
                "organizationalUnitName": "",
                "postalCode": "",
                "stateOrProvinceName": "",
                "streetAddress": "",
                "houseIdentifier": "",
                "serialNumber": "",
                "commonName": ""
              },
              "issuer": {
                "countryName": "",
                "organizationName": "",
                "organizationalUnitName": "",
                "commonName": ""
              },
              "serial": "",
              "notBefore": "",
              "notAfter": "",
              "subjectHash": "",
              "signatureAlgorithm": "",
              "fingerPrint": "",
              "publicKey": {
                "algorithm": ""
              },
              "altNames": [],
              "extensions": {
                "basicConstraints": "",
                "keyUsage": "",
                "extendedKeyUsage": "",
                "authorityKeyIdentifier": "",
                "subjectKeyIdentifier": "",
                "subjectAlternativeName": "",
                "cRLDistributionPoints": "",
                "authorityInformationAccess": "",
                "certificatePolicies": ""
              }
            },
            "validAadhaarDSC": ""
          },
          "address": "",
          "photo": "",
          "splitAddress": {
            "district": [
              ""
            ],
            "state": [
              [
                "",
                ""
              ]
            ],
            "city": [
              ""
            ],
            "pincode": "",
            "country": [
              "IN",
              "IND",
              "INDIA"
            ],
            "addressLine": "",
            "landMark": ""
          }
        },
        "details": {
          "userDetails": {
            "digilockerid": "",
            "name": "",
            "dob": "",
            "gender": "M",
            "eaadhaar": "Y"
          },
          "files": [
            {
              "name": "",
              "type": "file",
              "size": "",
              "date": "",
              "parent": "",
              "mime": [        ],
              "doctype": "",
              "description": "",
              "issuerid": "",
              "issuer": "",
              "id": ""
            },
       
          ]
        }
      }

2) Failure Scenario

a) When user clicks on “Return to signzy"

{
    "error": "user_cancelled",
    "message": "user cancelled",
    "requestId": "...request ID...",
    "status": "failure",
    "timestamp": 1678706980468
}

b) When user clicks on “Deny“ button

{
    "error": "access_denied",
    "message": "The user denied access to your application",
    "requestId": "...request ID...",
    "status": "failure",
    "timestamp": 1678707239614
}

Sample Error

{
  "error": {
    "statusCode": "...status code...",
    "name": "error",
    "message": "....reason....",
    "status": "...status code..."
  }
}

Error Parameter

PARAMETER NAME	DESCRIPTION
error	This parameter contains the error.
error.name	the name of the error
error.message	the error message
error.status	status of the api
error.statusCode	Request Status code from Signzy

Error Codes

CODE	DESCRIPTION
401	Authorization Token is invalid
409	If Upstream service not reachable

Getting help

Please feel free to contact us if you have any questions, require clarification, or have ideas for how to make the documents or any of our services better.

You can reach out to us at [email protected].