Aadhaar eSign API Integration: Developer Guide

Aadhaar eSign API lets your application embed legally valid document signing directly into your product flow — without sending users to an external website. The API connects your app to an Authentication Service Provider (ASP), which in turn interfaces with UIDAI to authenticate the signer via OTP and apply a cryptographic signature to the document.

This guide walks through how the API works, what you need before you start, the integration steps, and what to watch out for in production.

What Is the Aadhaar eSign API?

The Aadhaar eSign API is a set of HTTP endpoints provided by a UIDAI-approved ASP. When your application calls these endpoints with a document and a signer's Aadhaar number, the ASP orchestrates the following:

1. Sends an OTP to the signer's Aadhaar-linked mobile number via UIDAI
2. Receives the OTP from your app (entered by the signer)
3. Authenticates the OTP with UIDAI
4. Applies a digital signature certificate to the document
5. Returns the signed PDF to your application

The resulting signature is a PKI-based digital signature embedded in the PDF. It is verifiable by anyone with a standard PDF reader and is valid under Section 3A of the IT Act 2000.

The key point for developers: you are not implementing cryptography yourself. The ASP handles the UIDAI integration, the certificate issuance, and the signature application. Your job is to send the document and receive the signed output.

How the eSign Flow Works

Here is the end-to-end flow from the signer's perspective, and what happens technically at each step:

1. Document preparation (your app) Your backend converts the document to PDF format and generates a hash of the document. You send this to the ASP along with the signer's Aadhaar number and a callback URL.

2. OTP trigger (ASP to UIDAI) The ASP sends an OTP request to UIDAI. UIDAI generates a time-bound OTP and sends it via SMS to the mobile number linked to the Aadhaar.

3. OTP entry (signer, in your app) Your front-end shows an OTP input field. The signer enters the 6-digit OTP they received.

4. OTP submission (your app to ASP) Your app sends the OTP to the ASP along with a signing session identifier.

5. Authentication and signing (ASP to UIDAI to ASP) The ASP forwards the OTP to UIDAI for verification. On success, UIDAI returns an authentication token. The ASP uses this to issue a short-lived signing certificate tied to the signer's Aadhaar identity, then applies it to the document.

6. Signed document returned (ASP to your app) The ASP returns the signed PDF to your backend. You store this and show the signer a success confirmation.

The entire flow typically completes in 10–30 seconds.

Prerequisites Before You Integrate

1. ASP (Authentication Service Provider) account

You cannot connect to UIDAI directly. You must go through a UIDAI-approved ASP. Approved ASPs include SignSetu, Digio, eMudhra, Leegality, and others. For a detailed comparison, see the best Aadhaar eSign services in India.

2. Registered business entity

ASPs require you to be a registered business — a private limited company, LLP, or registered firm. Individual developers cannot access production Aadhaar eSign APIs.

3. API credentials from the ASP

After onboarding, you receive: API key or client ID/secret, base URL for sandbox and production environments, webhook or callback URL configuration.

4. Document in PDF format

The document must be a valid, non-encrypted PDF.

5. Signer's consent mechanism

Before triggering OTP, you must have obtained informed consent from the signer. Your UI must show a consent screen before the signing flow begins.

API Endpoints Overview

Endpoint structures vary by ASP, but the logical endpoints are consistent:

Initiate signing session POST /v1/esign/initiate — Payload includes document, signer Aadhaar number, callback URL, and metadata. Returns: session ID, OTP expiry time.

Submit OTP and complete signing POST /v1/esign/sign — Payload includes session ID and OTP. Returns: signed document and signing timestamp.

Check signing status GET /v1/esign/status/ — Returns: pending / completed / failed.

Verify signed document POST /v1/esign/verify — Payload: signed PDF. Returns: signature validity and signer identity.

Step-by-Step Integration

Step 1: Set up sandbox credentials — Register with your chosen ASP and get sandbox API keys.

Step 2: Prepare your document pipeline — Build a function that produces clean, signing-ready PDFs.

Step 3: Implement the consent screen — Before any Aadhaar number is collected, show the user a consent screen.

Step 4: Initiate the signing session — Call the initiate endpoint from your backend (not frontend).

Step 5: Collect the OTP in your frontend — Show an OTP input field with a countdown timer.

Step 6: Submit OTP and retrieve signed document — POST the OTP to your backend, which calls the sign endpoint.

Step 7: Store and confirm — Save the signed PDF, update the document record, show success screen.

Step 8: Handle webhooks for async flows — Configure your callback URL to receive signing completion events.

Security Considerations

Never expose API keys on the frontend. All calls to the ASP must go through your backend.

Do not store full Aadhaar numbers. The Aadhaar Act 2016 prohibits storage by unauthorised entities. Collect, pass to ASP in a single call, and discard.

Use HTTPS everywhere. All endpoints must be over HTTPS.

Validate signed documents after signing. Call the verify endpoint to confirm the signature is valid.

Rate limit your OTP initiation endpoint. No more than 3 OTP requests per Aadhaar number per hour is a reasonable default.

Log signing events, not Aadhaar data. Record document ID, session ID, timestamp, success/failure — not the Aadhaar number.

Testing vs Production

Aspect	Sandbox	Production
UIDAI OTP	Simulated (test OTP)	Real UIDAI SMS OTP
Aadhaar numbers	Test numbers from ASP	Real Aadhaar numbers
Signed certificates	Test certificates (not legally valid)	Real certificates (legally valid)
Cost	Free or minimal	Per-signature charges apply
Rate limits	Relaxed	Enforced

Move to production only after end-to-end sandbox testing passes, security review is completed, and consent mechanism is reviewed.

Pricing Models

Typical per-signature rates in India:

• Low volume (< 500 signs/month): INR 10–25 per signature
• Medium volume (500–5,000/month): INR 6–15 per signature
• High volume (> 5,000/month): INR 3–8 per signature (negotiated)

Some ASPs charge a setup fee (INR 5,000–25,000 one-time).

Choosing an ASP: What Matters for Developers

Documentation quality: A well-documented API with working sandbox examples saves weeks of integration time.

Sandbox availability: Prefer ASPs that give sandbox access quickly so you can prototype before committing.

Uptime and SLA: Ask for historical uptime data and check whether they publish a status page.

Support responsiveness: An ASP with a technical Slack channel or dedicated integration support is far more valuable than one with only email support.

SignSetu's API is designed specifically for developers building Indian products, with straightforward integration, INR-denominated per-signature pricing, and sandbox access without requiring full KYC upfront. This makes it a practical starting point if you are prototyping.