eKYC Setu API

Introduction

The eKYC Setu APIs enable Aadhaar-based electronic Know Your Customer (eKYC) using a secure web redirection flow. The solution ensures Aadhaar data capture, OTP authentication, and KYC processing occur entirely within NPCI’s secure environment, while the entity consumes only encrypted responses via APIs and callbacks.

Objective:

Secure Aadhaar-based eKYC using OTP

Avoid Aadhaar storage at entity systems

Provide configurable redirection and callback handling

Support Aadhaar PDF and image delivery in Base64 or URL form

The eKYC Setu is a 2 step API:

Create URL API: Financial Institution generates a web redirection link on which customer will be routed for consent with OTP.

Fetch eKYC data: Using requestID, FI can fetch Aadhaar holder details after consent.

High level flow

Secure Aadhaar-based eKYC using OTP

Avoid Aadhaar storage at entity systems

Provide configurable redirection and callback handling

Support Aadhaar PDF and image delivery in Base64 or URL form

Ensure UIDAI and NPCI compliance

Create URL API

This API generates a web redirection link on which the customer will be routed for consent with OTP. This link can be embedded in Start Aadhaar verification button in your web/mobile application or can be sent as a URL in SMS/Email.

Sample CURL

Preproduction

Production

curl --location --request POST 'https://api-preproduction.signzy.app/api/v3/eKycSetu/createUrl' \
--header 'Authorization: <accessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "orgId": "979088",
  "txnId": "SET1234567890123456788888888888888",
  "consentFlag": "Y",
  "mode": "SELF",
  "callBackUrl": "https://entity.com/ekyc/callback",
  "redirectionUrl": "https://entity.com/ekyc/result",
  "pdfEnabled": "Y",
  "getBase64Files": "Y",
  "getAadhaarjpeg": "N"
}'

curl --location --request POST 'https://api.signzy.app/api/v3/eKycSetu/createUrl' \
--header 'Authorization: <accessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "aadhaarNumber": "<Aadhaar Number>"
}'

Input Parameters

Input Parameter	Data type	Required/Optional	Description
Authorization	String	Required	Contains the id parameter returned from the login step
Content-Type	String	Required	application/json
orgId	String	Required	6-digit NPCI assigned entity ID
txnId	String	Required	Unique transaction ID (max 35 chars)
consentFlag	String	Required	Y/N (Must be Y to get response)
mode	String	Required	Self/Assisted
callBackUrl	String	Optional	URL where callback response with Aadhaar details will be received.
redirectionUrl	String	Required	URL where user is redirected after success/failure
pdfEnabled	String	Optional	Y/N (If you want to receive Aadhaar pdf, default is Y)
getPersistURL	String	Optional	Y/N (Aadhaar PDF in Base64 if blank or N, else persist URL)
getAadhaarjpeg	String	Optional	Y/N (Aadhaar image in JPEG if Y)

Sample Response

Parameters Name	Data Type	Description
txnId	String	The unique id which was passed in the request packet
url	String	RUL on which end customer has to be redirected for entering Aadhaar and submitting OTP

Output Parameters

{
    "result": {
        "url": "https://api.digitallocker.gov.in/public/oauth2/1/authorize?client_id=3DF9D55E&code_challenge=2R4H2pVG-SmhvTDn0xQlLcPWqAvp15XUufUBbQ0Sd2I&code_challenge_method=S256&dl_flow=signup&redirect_uri=https%3A%2F%2Fdigilocker.signzy.tech%2Fdigilocker-auth-complete&response_type=code&state=652d08105aac750011ff8a71",
        "txnId": "652d08105aac750011ff8a71"
    }
}

Callback response

The below response will be received in the callback URL shared in the Create URL request API.

Preproduction

Production

{
  "txnId": "SET1234567890123456788888888888888",
  "status": "SUCCESS",
  "resultCode": "0",
  "resultMessage": "eKYC completed successfully",
  "kycMode": "OTP",
  "userRedirectStatus": "SUCCESS",
  "uidData": {
    "uid": "XXXXXXXX1234",
    "tkn": "UIDAI_TOKEN_VALUE",
      "name": "RAHUL KUMAR",
      "dob": "1990-08-15",
      "gender": "M",
      "co": "S/O RAMESH KUMAR",
      "house": "123",
      "street": "MG ROAD",
      "lm": "NEAR METRO STATION",
      "loc": "INDIRANAGAR",
      "vtc": "BENGALURU",
      "subdist": "BENGALURU EAST",
      "dist": "BENGALURU",
      "state": "KARNATAKA",
      "country": "INDIA",
      "pc": "560038",
      "po": "INDIRANAGAR"
    },
    "lData": {
      "lang": "HI",
      "name": "राहुल कुमार",
      "co": "रामेश कुमार",
      "house": "१२३",
      "street": "एम जी रोड",
      "lm": "मेट्रो स्टेशन के पास",
      "loc": "इंदिरानगर",
      "vtc": "बेंगलुरु",
      "subdist": "बेंगलुरु पूर्व",
      "dist": "बेंगलुरु",
      "state": "कर्नाटक",
      "country": "भारत",
      "pc": "560038",
      "po": "इंदिरानगर"
    },
    "photo": {
      "file": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
    },
    "eAadhaar": {
      "type": "pdf",
      "file": "JVBERi0xLjQKJ..."
    },
    "eAadhaar": {
      "type": "jpeg",
      "file": "JVBERi0xLjQKJ..."
    }
  },
  "timestamp": "2026-01-16T15:05:30+05:30",
}

{
  "txnId": "SET1234567890123456788888888888888",
  "status": "SUCCESS",
  "resultCode": "0",
  "resultMessage": "eKYC completed successfully",
  "kycMode": "OTP",
  "userRedirectStatus": "SUCCESS",
  "uidData": {
    "uid": "XXXXXXXX1234",
    "tkn": "UIDAI_TOKEN_VALUE",
      "name": "RAHUL KUMAR",
      "dob": "1990-08-15",
      "gender": "M",
      "co": "S/O RAMESH KUMAR",
      "house": "123",
      "street": "MG ROAD",
      "lm": "NEAR METRO STATION",
      "loc": "INDIRANAGAR",
      "vtc": "BENGALURU",
      "subdist": "BENGALURU EAST",
      "dist": "BENGALURU",
      "state": "KARNATAKA",
      "country": "INDIA",
      "pc": "560038",
      "po": "INDIRANAGAR"
    },
    "lData": {
      "lang": "HI",
      "name": "राहुल कुमार",
      "co": "रामेश कुमार",
      "house": "१२३",
      "street": "एम जी रोड",
      "lm": "मेट्रो स्टेशन के पास",
      "loc": "इंदिरानगर",
      "vtc": "बेंगलुरु",
      "subdist": "बेंगलुरु पूर्व",
      "dist": "बेंगलुरु",
      "state": "कर्नाटक",
      "country": "भारत",
      "pc": "560038",
      "po": "इंदिरानगर"
    },
    "photo": {
      "file": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
    },
    "eAadhaar": {
      "type": "pdf",
      "file": "JVBERi0xLjQKJ..."
    },
    "eAadhaar": {
      "type": "jpeg",
      "file": "JVBERi0xLjQKJ..."
    }
  },
  "timestamp": "2026-01-16T15:05:30+05:30",
}

Fetch eKYC data API

Parameter Name	Type	Description
txnId	String	Unique transaction identifier for the eKYC request
status	String	Overall status of the eKYC process ( SUCCESS , FAILURE , CANCELLED , EXPIRED )
resultCode	String	Response code indicating outcome of the eKYC process
resultMessage	String	Result message
kycMode	String	Mode of eKYC performed (OTP)
userRedirectStatus	String	Status used to determine user redirection outcome
uidData	Object	Container object holding all Aadhaar-related details
uidData.uid	String	Masked Aadhaar number of the resident
uidData.tkn	String	UIDAI-issued token for the Aadhaar number
uidData.name	String	Name of the Aadhaar holder (English)
uidData.dob	String (YYYY-MM-DD)	Date of birth of the Aadhaar holder
uidData.gender	String	Gender of the Aadhaar holder (M / F / T)
uidData.co	String	Care of (Father/Mother/Spouse)
uidData.house	String	House or building number
uidData.street	String	Street name
uidData.lm	String	Landmark
uidData.loc	String	Locality
uidData.vtc	String	Village / Town / City
uidData.subdist	String	Sub-district
uidData.dist	String	District
uidData.state	String	State
uidData.country	String	Country
uidData.pc	String	Postal / PIN code
uidData.po	String	Post office
uidData.lData	Object	Address and name details in local language
uidData.lData.lang	String	Language code for local language data (e.g., HI)
uidData.lData.name	String	Name in local language
uidData.lData.co	String	Care of in local language
uidData.lData.house	String	House number in local language
uidData.lData.street	String	Street name in local language
uidData.lData.lm	String	Landmark in local language
uidData.lData.loc	String	Locality in local language
uidData.lData.vtc	String	Village / Town / City in local language
uidData.lData.subdist	String	Sub-district in local language
uidData.lData.dist	String	District in local language
uidData.lData.state	String	State in local language
uidData.lData.country	String	Country in local language
uidData.lData.pc	String	Postal / PIN code
uidData.lData.po	String	Post office in local language
uidData.photo	Object	Aadhaar holder photograph details
uidData.photo.file	String (Base64)	Base64-encoded JPEG photo of the resident
uidData.eAadhaar.pdf	Object	e-Aadhaar document details
uidData.eAadhaarPdf.type	String	e-Aadhaar file type (pdf)
uidData.eAadhaarPdf.file	String (Base64 / URL)	Base64 data or secure URL of signed e-Aadhaar
uidData.eAadhaar.Jpeg	String	e-Aadhaar document details
uidData.eAadhaarJpeg.type	String (Base64 / URL)	e-Aadhaar file type (jpeg)
uidData.eAadhaarJpeg.file	String	Base64 data or secure URL of signed e-Aadhaar

Fetch eKYC data API

Using requestID, FI can fetch Aadhaar holder details after successful customer's consent.

Sample CURL

Preproduction

Production

curl --location --request POST 'https://api-preproduction.signzy.app/api/v3/eKycSetu/fetchData' \
--header 'Authorization: <accessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "orgId": "979088",
  "txnId": "SET1234567890123456788888888888888",
}'

curl --location --request POST 'https://api.signzy.app/api/v3/eKycSetu/fetchData' \
--header 'Authorization: <accessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "orgId": "979088",
  "txnId": "SET1234567890123456788888888888888",
}'

Input Parameters

Input Parameter	Required/Optional	Explanation
Authorization	Required	Contains the id parameter returned from the login step
Content-Type	Required	application/json
orgId	Required	Organization ID given by NPCI
txnId	Required	The unique id which was passed in the request packet

Sample Response

{
  "txnId": "SET1234567890123456788888888888888",
  "status": "SUCCESS",
  "resultCode": "0",
  "resultMessage": "eKYC completed successfully",
  "kycMode": "OTP",
  "userRedirectStatus": "SUCCESS",
  "uidData": {
    "uid": "XXXXXXXX1234",
    "tkn": "UIDAI_TOKEN_VALUE",
      "name": "RAHUL KUMAR",
      "dob": "1990-08-15",
      "gender": "M",
      "co": "S/O RAMESH KUMAR",
      "house": "123",
      "street": "MG ROAD",
      "lm": "NEAR METRO STATION",
      "loc": "INDIRANAGAR",
      "vtc": "BENGALURU",
      "subdist": "BENGALURU EAST",
      "dist": "BENGALURU",
      "state": "KARNATAKA",
      "country": "INDIA",
      "pc": "560038",
      "po": "INDIRANAGAR"
    },
    "lData": {
      "lang": "HI",
      "name": "राहुल कुमार",
      "co": "रामेश कुमार",
      "house": "१२३",
      "street": "एम जी रोड",
      "lm": "मेट्रो स्टेशन के पास",
      "loc": "इंदिरानगर",
      "vtc": "बेंगलुरु",
      "subdist": "बेंगलुरु पूर्व",
      "dist": "बेंगलुरु",
      "state": "कर्नाटक",
      "country": "भारत",
      "pc": "560038",
      "po": "इंदिरानगर"
    },
    "photo": {
      "file": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
    },
    "eAadhaarpdf": {
      "type": "pdf",
      "file": "JVBERi0xLjQKJ..."
    },
    "eAadhaarjpeg": {
      "type": "jpeg",
      "file": "JVBERi0xLjQKJ..."
    }
  },
  "timestamp": "2026-01-16T15:05:30+05:30",
}

Output Parameters

Parameter Name	Type	Description
txnId	String	Unique transaction identifier for the eKYC request
status	String	Overall status of the eKYC process ( SUCCESS , FAILURE , CANCELLED , EXPIRED )
resultCode	String	Response code indicating outcome of the eKYC process
resultMessage	String	Result message
kycMode	String	Mode of eKYC performed (OTP)
userRedirectStatus	String	Status used to determine user redirection outcome
uidData	Object	Container object holding all Aadhaar-related details
uidData.uid	String	Masked Aadhaar number of the resident
uidData.tkn	String	UIDAI-issued token for the Aadhaar number
uidData.name	String	Name of the Aadhaar holder (English)
uidData.dob	String (YYYY-MM-DD)	Date of birth of the Aadhaar holder
uidData.gender	String	Gender of the Aadhaar holder (M / F / T)
uidData.co	String	Care of (Father/Mother/Spouse)
uidData.house	String	House or building number
uidData.street	String	Street name
uidData.lm	String	Landmark
uidData.loc	String	Locality
uidData.vtc	String	Village / Town / City
uidData.subdist	String	Sub-district
uidData.dist	String	District
uidData.state	String	State
uidData.country	String	Country
uidData.pc	String	Postal / PIN code
uidData.po	String	Post office
uidData.lData	Object	Address and name details in local language
uidData.lData.lang	String	Language code for local language data (e.g., HI)
uidData.lData.name	String	Name in local language
uidData.lData.co	String	Care of in local language
uidData.lData.house	String	House number in local language
uidData.lData.street	String	Street name in local language
uidData.lData.lm	String	Landmark in local language
uidData.lData.loc	String	Locality in local language
uidData.lData.vtc	String	Village / Town / City in local language
uidData.lData.subdist	String	Sub-district in local language
uidData.lData.dist	String	District in local language
uidData.lData.state	String	State in local language
uidData.lData.country	String	Country in local language
uidData.lData.pc	String	Postal / PIN code
uidData.lData.po	String	Post office in local language
uidData.photo	Object	Aadhaar holder photograph details
uidData.photo.file	String (Base64)	Base64-encoded JPEG photo of the resident
uidData.eAadhaar.pdf	Object	e-Aadhaar document details
uidData.eAadhaarPdf.type	String	e-Aadhaar file type (pdf)
uidData.eAadhaarPdf.file	String (Base64 / URL)	Base64 data or secure URL of signed e-Aadhaar
uidData.eAadhaar.Jpeg	String	e-Aadhaar document details
uidData.eAadhaarJpeg.type	String (Base64 / URL)	e-Aadhaar file type (jpeg)
uidData.eAadhaarJpeg.file	String	Base64 data or secure URL of signed e-Aadhaar

Note:

FI needs to get their eKYC Setu credentials created through NPCI.

Those credentials and Digital Signature Certificate needs to be configured for accessing these APIs

OTP Retry Limit

Resident is allowed a maximum of 3 OTP retry attempts.

Resend OTP option is enabled after 30 seconds from the previous request.

OTP Validity

Expired OTP submissions will result in authentication failure.

Consent Mandatory

Aadhaar capture and eKYC processing is enabled only if resident consent is Yes.

If consent is denied, the transaction is marked as CANCELLED.

Redirection Handling

Post eKYC completion (success/failure/cancel), the user is redirected to the Redirection URL provided in the Create URL API.

Backend response is delivered separately to the Callback URL.

Callback Delivery

Callback response is triggered only after resident action (consent / OTP submission).

KYC Data Fetch Window

Entity backend must fetch eKYC data within 5 minutes of successful completion.

Maximum 3 retry attempts are allowed within this window.

Document Delivery Mode

Aadhaar PDF and photo delivery depends on:

getBase64Files

getAadhaarjpeg

If Base64 is disabled, documents are provided via secure, time-bound URLs.

Language Data Availability

Local language data (lData) is provided only if available in UIDAI records.

Absence of local language data does not indicate transaction failure.

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].