> For the complete documentation index, see [llms.txt](https://docs.emudhradigital.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.emudhradigital.com/documentation/esign-v2-online-aadhaar-ekyc/api-specification.md).

# API Specification

eSign v2 follows CCA **eSign API 2.1**. The API is stateless over HTTPS; request and response payloads are XML (`Content-Type: application/xml`), each digitally signed by the sender.

## Request — `<Esign>`

```xml
<Esign ver="2.1" sc="Y" ts="2026-10-12T10:15:30" txn="ASP-20261012-000123"
       ekycId="" ekycIdType="A" aspId="ASPXXXX0001"
       AuthMode="1" responseSigType="PKCS7pdf"
       responseUrl="https://asp.example.com/esign/response">
  <Docs>
    <InputHash id="1" hashAlgorithm="SHA256"
               docInfo="Loan agreement 4521">a3f5…(64 hex chars)…9c</InputHash>
  </Docs>
  <Signature><!-- ASP XML-DSig over the request --></Signature>
</Esign>
```

### `<Esign>` attributes

| Attribute         | Required | Description                                                                              |
| ----------------- | -------- | ---------------------------------------------------------------------------------------- |
| `ver`             | Yes      | API version. Use `2.1`.                                                                  |
| `sc`              | Yes      | Signer consent. Only valid value is `Y`.                                                 |
| `ts`              | Yes      | Request timestamp, ISO 8601, IST. Must be within ±30 minutes of server time.             |
| `txn`             | Yes      | ASP transaction ID; logged and echoed in the response. Must be unique for the ASP.       |
| `ekycIdType`      | Yes      | eKYC ID type. `A` = Aadhaar.                                                             |
| `ekycId`          | No       | UID token. If supplied, must match the token in the eKYC response (`ESP-906` otherwise). |
| `aspId`           | Yes      | ASP organisation ID issued by eMudhra.                                                   |
| `AuthMode`        | Yes      | `1` OTP/TOTP, `2` fingerprint, `3` iris, `4` face.                                       |
| `responseSigType` | Yes      | `rawrsa`, `rawecdsa`, `PKCS7`, `PKCS7pdf`, `PKCS7complete`.                              |
| `responseUrl`     | Yes      | HTTPS URL to which the response is delivered.                                            |

### `<InputHash>`

| Attribute       | Required | Description                                       |
| --------------- | -------- | ------------------------------------------------- |
| `id`            | Yes      | Must be `1` — only one document per request.      |
| `hashAlgorithm` | Yes      | `SHA256`.                                         |
| `docInfo`       | Yes      | Description shown to the signer, ≤ 50 characters. |
| *(content)*     | Yes      | SHA-256 hash of the document, hex encoded.        |

### Signature types

| `responseSigType` | Returned signature                                                                                          |
| ----------------- | ----------------------------------------------------------------------------------------------------------- |
| `rawrsa`          | Raw PKCS#1 RSA signature                                                                                    |
| `rawecdsa`        | Raw ECDSA signature                                                                                         |
| `PKCS7`           | CMS SignedData with signer certificate only, no revocation data                                             |
| `PKCS7pdf`        | CMS with issuer chain to root, CRL/OCSP and CA timestamp — for PDF embedding (OCSP only if CRL > 5 entries) |
| `PKCS7complete`   | CMS with all issuer certificates and revocation information in unsigned attributes                          |

## Response — `<EsignResp>`

```xml
<EsignResp status="1" ts="2026-10-12T10:16:42" txn="ASP-20261012-000123"
           resCode="9F2C…(32 chars)" errCode="NA" errMsg="NA">
  <UserX509Certificate>MIIF…base64…</UserX509Certificate>
  <Signatures>
    <DocSignature id="1" sigHashAlgorithm="SHA256" error="">MIAG…base64…</DocSignature>
  </Signatures>
  <Signature><!-- ESP XML-DSig over the response --></Signature>
</EsignResp>
```

| Attribute / element   | Description                                                  |
| --------------------- | ------------------------------------------------------------ |
| `status`              | `1` success, `0` failure                                     |
| `ts`                  | Response timestamp                                           |
| `txn`                 | Echo of the request `txn`                                    |
| `resCode`             | eMudhra unique response code — store in your audit log       |
| `errCode` / `errMsg`  | Error code and message; `NA` on success                      |
| `UserX509Certificate` | Base64 signer certificate (can be saved as a PEM `.cer`)     |
| `DocSignature`        | Signature for `InputHash` `id`; format per `responseSigType` |
| `Signature`           | eMudhra XML signature — **always verify before use**         |

The response contains no Aadhaar number or demographic data.

## Endpoints

| Environment | Purpose            | URL                      |
| ----------- | ------------------ | ------------------------ |
| UAT         | Request submission | *Provided at onboarding* |
| Production  | Request submission | *Provided at onboarding* |