NeSL e-Stamp

This API is used to create an e-Stamping and Digital Signing request for a legal document.

UI Mode (Optional Review Before Submission)

Set uiMode=true in the request body to defer submission to NeSL. When enabled:

• The transaction is persisted in a PendingReview state. The submission to NeSL is not made yet.

• The response returns a uiUrl in addition to EStampId. The workflow/NeSL fields stay empty until confirmation.

• Open uiUrl in a browser (no portal login required) — the lightweight review screen shows the uploaded PDF, pre-filled eStamp details and signer coordinates so the customer can adjust them.

• Clicking Confirm & Submit in the UI triggers the actual NeSL submission and the normal webhook flow resumes — your configured ResponseWebhookUrl fires on status changes just as in the legacy flow.

• The signed URL expires after 7 days by default (configurable per-environment). Tampered or expired links return 401/410.

• Backward compatibility: omitting uiMode (or setting it false) is byte-identical to today's direct-submission behaviour.

Example response shapes:

• uiMode=false (default): { "eStampId": "...", "neslURL": "https://.../sign?...", "parallelSigningURLs": [...] }
• uiMode=true: { "eStampId": "...", "neslURL": "", "parallelSigningURLs": null, "uiUrl": "https://<frontend>/nesl-stamp/review/<txId>?sig=...&exp=..." }

It allows you to upload a PDF, apply the required stamp duty as per state regulations, and define the signing flow for multiple parties all in a single API call.

For example, a bank can use this API to:

• Apply a stamp duty for a Loan Agreement between the Bank and the Borrower.

• Simultaneously apply a stamp duty for a Guarantee Bond between the Bank and the Guarantor.

• Define who signs, in what order, and where on the document the signature box appears.

All of this happens in one request instead of multiple separate calls.

Q. What is documentInfo and why is it required?

documentInfo is the section that carries the actual PDF file that needs to be e-stamped and signed.

It contains two fields:

• name - Required. The display name of the file, for example Loan_Agreement.pdf. Maximum 40 characters; letters, digits, spaces and the characters , @ _ . ' - ( ) [ ] only.

• content - Required. The entire PDF file converted to a Base64 string. Maximum size 20 MB. The PDF must not already be signed.

Q. Who are firstParty and secondParty?

firstParty is typically the Lender (the Bank) and secondParty is typically the Borrower. Both are mandatory because NeSL requires both parties to generate a legally valid stamp certificate.

Each party object must contain:

• name - Full legal name as it should appear on the stamp certificate.

• signerName - Optional. The individual who signs on behalf of the entity (e.g., "Virag Kubadia" for "SignCare Solutions Pvt Ltd"). When provided, this name is shown in the signature box instead of name. See the dedicated signerName Q&A below for full details.

• email - The email address where the signing invitation link will be sent. Must be different for every party in the request.

• phone - A 10-digit mobile number. Must be Aadhaar-linked if Aadhaar OTP signing is used.

• pan - PAN number for KYC verification. NeSL cross-checks this against government records. Format: AAAAA9999A (5 uppercase letters, 4 digits, 1 uppercase letter). Must be different for every party in the request.

• pin - Conditional: required when stateCode is West Bengal (WB) or Madhya Pradesh (MP); optional otherwise. 6-digit postal PIN code. See the dedicated pin Q&A below.

• doi - Date of incorporation (for an entity) or date of birth (for an individual), as an ISO 8601 date such as 1990-01-15. NeSL uses this to verify the PAN against official records.

• signType - A list of allowed signing methods, at least one. Send each value as a separate array item. Accepted values (case-sensitive): Aadhaar (OTP-based eSign), Electronic (email OTP), DSC (hardware token).

Each party object also supports these optional fields for signing position, company seal, and Aadhaar verification:

• signAppearance - Optional. Corner of the page for the signature box, sent as a number. Values: 1 (Top_Left), 2 (Top_Right), 3 (Bottom_Left), 4 (Bottom_Right), 5 (PageCoordinates, requires pageInfo). Default: 3 (Bottom_Left).

• pageToBeSigned - Conditional: required unless pageInfo is provided. Which pages this party should sign, sent as a number. Values: 1 (FIRST), 2 (LAST), 3 (EVEN), 4 (ODD), 5 (ALL), 6 (SPECIFY). There is no default value; send 5 to sign every page.

• pageNumber - Conditional: required when pageToBeSigned is 6 (SPECIFY) and pageInfo is not provided. Comma-separated page numbers (e.g., "1,3,7").

• pageInfo - Optional. A list of manual page coordinates used instead of automatic placement for this party.

• signatorySealInfo - Optional. Adds a company seal text ("For, OrgName" above and seal type text below) around the signature box.

• aadhaarVerificationOptions - Optional. When signType includes "Aadhaar", provides the invitee's demographic details for NeSL to cross-verify before the Aadhaar eSign. The cross-check runs only when verifyInvitee is true. See the dedicated Q&A below for full details.

Q. When should I use coBorrowers?

coBorrowers is an array that allows you to add multiple additional signatories under the same role.

Each co-borrower follows the same structure as firstParty and secondParty (name, email, phone, doi, signType), except that pan is optional and signerName is not supported. Co-borrowers also support ovdType and ovdValue as an alternative to pan when the co-borrower does not have a PAN card. See the dedicated ovdType/ovdValue Q&A below. If there are no co-borrowers, omit the field or pass null.

Q. What is the guarantor field?

The guarantor is an optional single party object used when a third individual is guaranteeing the loan agreement.

It uses the same fields as firstParty and secondParty (name, email, phone, doi, signType). The guarantor also supports ovdType and ovdValue as an alternative to pan — see the dedicated ovdType/ovdValue Q&A below.

For the guarantor's stamp duty, add a separate entry in the root additionalArticles list where firstPartyName is the Lender and secondPartyName is the Guarantor.

Business rule: The Lender (firstParty) stays constant. The Guarantor replaces the Borrower as the second party only on the guarantor-specific stamp articles.

Q. What are ovdType and ovdValue and when should I use them?

OVD stands for Officially Valid Document. These two fields are available on coBorrowers and guarantor only — they are NOT available on firstParty or secondParty, where PAN is always mandatory.

Use ovdType and ovdValue when the co-borrower or guarantor does not have a PAN card. Instead of PAN, you provide an alternate government-issued identity document for NeSL KYC verification.

ovdType — The type of the identity document. Use one of these values (spelling must match; letter case is ignored):

• passport
• driving license
• voter id
• others

ovdValue — The document number of the OVD. The format is checked for each type:

• passport: 1 letter followed by 7 digits (e.g., A1234567).

• driving license: 2 letters followed by 13 digits, 15 characters in total (e.g., MH0120100012345). Hyphens and spaces are ignored.

• voter id: 3 letters followed by 7 digits (e.g., ABC1234567).

• others: any non-empty value.

Rules:

• ovdType and ovdValue must always be provided together — you cannot send one without the other.

• Send either pan or the ovdType/ovdValue pair, not both. A party that has both is rejected.

• If the party has a PAN, provide pan and leave ovdType and ovdValue as null.

• If the party does not have a PAN, provide ovdType and ovdValue and leave pan as null.

• Every coBorrower and the guarantor must have either a PAN or an OVD. Each pan, email and ovdValue must be different across all parties in the request.

Q. What is stateCode and where do I get it?

stateCode is the two-letter code for the Indian state where the stamp duty is to be registered.

Different states have different stamp duty rates and article codes, so this field is mandatory. Example: GJ for Gujarat, MH for Maharashtra, KA for Karnataka. The code is not case-sensitive.

Call the /states API first to get a complete list of valid state codes. Any other code is rejected.

Q. What is referenceId?

referenceId is your unique transaction identifier used to track this workflow end-to-end in your own system. It must be unique per request, is 1 to 64 characters long, and may contain only letters, digits, hyphen (-) and underscore (_). A reference that was already used is rejected.

Q. What are additionalArticles and why are they required?

additionalArticles defines the legal and financial details for each stamp certificate to be generated.

A single loan can involve multiple stamp articles. For example, one article for the main loan agreement and a separate one for a guarantee bond.

Each article entry contains:

• firstPartyName - The name printed as the first party on the official stamp paper. Always the Lender.

• secondPartyName - The name printed as the second party on the official stamp paper. The Borrower for loan articles, or the Guarantor for guarantee articles.

• stampdutyPaidBy - The name of the party who will pay the stamp duty (note the lowercase "d" in the field name). A legal requirement on the stamp certificate. It must match this article's firstPartyName or secondPartyName (letter case is ignored); any other name is rejected.

• articleCode - A unique code for the document type (e.g., mortgage deed, acknowledgement of debt). Call the /article-code API with your stateCode to get valid codes.

• amount - The stamp duty value in rupees (INR), as a number. Must be greater than zero. The total of all article amounts is debited from your NeSL wallet.

• considerationPrice - The total transaction or loan value for this article in rupees, sent as a string (e.g., "100000").

• description - An optional short description of the transaction.

All fields except description are required, and at least one article must be sent.

Q. Why are firstPartyName and secondPartyName required inside additionalArticles even though firstParty and secondParty are already provided?

firstParty and secondParty at the root level define who signs the document digitally. However, firstPartyName and secondPartyName inside each additionalArticle define the names that are physically printed on the official NeSL stamp certificate.

These can differ per article. For example, a single request may have one article for the Borrower (where secondPartyName is the Borrower) and another article for the Guarantor (where secondPartyName is the Guarantor). This is why each article must explicitly declare its own party names.

Q. How do I find the correct articleCode?

First call the /states API to get your state code. Then call the /article-code API passing the stateCode as a parameter. This returns all available document types and their article codes for that state.

Q. What does sequentialSigning control?

sequentialSigning is optional and defaults to true. It determines the order in which signing invitations are sent. The order is firstParty, secondParty, coBorrowers (in array order), then guarantor. Omit the field to use the default; do not send null.

• true: Signers are invited one at a time in the order defined. The next person is notified only after the previous one has signed.

• false: All signers receive the invitation at the same time and can sign in any order.

Q. How do I control where each person signs?

Positioning is now handled individually for each party (FirstParty, SecondParty, CoBorrowers, and Guarantor) using three properties inside each party object:

• signAppearance - Optional. Defines the corner of the page for the signature box. Values: 1 (Top_Left), 2 (Top_Right), 3 (Bottom_Left), 4 (Bottom_Right), 5 (PageCoordinates, requires pageInfo). Default: 3.

• pageToBeSigned - Conditional: required unless pageInfo is provided. Defines which pages this party should sign. Values: 1 (FIRST), 2 (LAST), 3 (EVEN), 4 (ODD), 5 (ALL), 6 (SPECIFY). There is no default value.

• pageNumber - Conditional: required if pageToBeSigned is set to 6 (SPECIFY) and pageInfo is not provided. Provide a comma-separated list of page numbers (e.g., "1,3,7").

Optional: Manual PageInfo at Party Level If you need pixel-perfect manual control, each party also has an optional pageInfo list. If provided, those boxes are used instead of the automated signAppearance placement for that specific party. This allows you to define exact coordinates per page for every participant.

Each pageInfo entry has pageSize (page height in points), pageWidth (page width in points) and a pdfCoordinates list. Each coordinate box has:

• page - Send "ALL" to use the box on every page; otherwise leave it empty and set pageNumber.

• pageNumber - Comma-separated 1-based page numbers (e.g., "1,3"). Required when page is not "ALL".

• x1, y1 - Left and top position of the box, in points from the top-left corner of the page.

• x2, y2 - Width and height of the box, in points (not the bottom-right corner).

This flexible structure allows a Co-Borrower to sign pages 1-3 while a Guarantor signs only the Last page, all within a single request.

Q. What is responseWebhookUrl?

responseWebhookUrl is your server endpoint where SignCare will POST real-time notifications for signing events such as party signed, document completed, or rejected.

This is optional. If not provided, the system falls back to the webhook URL configured in your account settings.

Q. What is redirectUrl?

redirectUrl is the URL where the signer is redirected in their browser after completing the signing process. Optional, used to bring the user back to your application.

Q. Why is doi mandatory?

doi is the date of incorporation (for an entity) or date of birth (for an individual). It is a mandatory requirement from NeSL to register the stamping transaction and verify each party against the official government PAN database. Send it as an ISO 8601 date, for example 1990-01-15.

Commonly Asked Questions

Q. What is the role of the articleCode?

Every state has different codes for different types of legal instruments (e.g., Indemnity Bond vs. Affidavit). You must provide the correct code corresponding to the state selected in stateCode to ensure legal validity.

Q. How do coBorrowers differ from the secondParty?

While both are signatories, secondParty is usually the primary counterparty, whereas coBorrowers is an array that allows you to add multiple additional signatories under the same role.

Q. Why are firstPartyName and secondPartyName required inside additionalArticles?

Even though firstParty and secondParty are already defined at the root level, additionalArticles can cover multiple stamp certificates — each potentially involving different parties (e.g., a borrower article and a guarantor article).

firstPartyName and secondPartyName inside additionalArticles represent the names that are physically printed on the official stamp certificate issued by NeSL. These may differ per article — for example, in a borrower article the secondPartyName is the borrower, while in a guarantor article the secondPartyName is the guarantor. This is why these fields must be explicitly set per article.

Q. Why is doi required?

doi is the date of incorporation (for an entity) or date of birth (for an individual). It is a mandatory field for NeSL to register the stamping transaction and verify the party against the PAN database.

Q. What is signatorySealInfo and when should I use it?

signatorySealInfo is an optional object inside each party that adds a company seal text around the signature box on the PDF. It is typically used when the signer is signing on behalf of a company or organization.

When provided, the system renders "For, [OrganizationName]" above the signature box and a seal type label (e.g., "Authorised Signatory") below it.

It contains two fields:

• name - The name of the organization (e.g., "ABC Bank Ltd"). This is printed as "For, ABC Bank Ltd" above the signature box.

• sealType - Defines the label printed below the signature box. Values: 1 (Authorised Signatory), 2 (Director), 3 (Company Seal).

If signatorySealInfo is null or not provided for a party, no company seal text is added — only the bare signature box appears.

Q. What is signerName and when should I use it?

signerName is an optional field available on firstParty, secondParty, and guarantor. It is NOT available on coBorrowers — co-borrowers always sign as themselves.

Use signerName when the party is a company or organization and a specific individual is signing on its behalf. When provided, this individual's name is displayed inside the signature box on the document and in the UiMode review screen instead of the entity name.

Example scenario: The first party is a bank named "SignCare Solutions Pvt Ltd". The person actually signing on the bank's behalf is "Virag Kubadia". In this case:

• name = "SignCare Solutions Pvt Ltd" (the legal entity — used for NeSL stamp certificate)

• signerName = "Virag Kubadia" (the individual — shown in the signing box on the document)

If signerName is not provided, the party's name is used as the label inside the signing box — which is the correct behaviour when an individual is signing for themselves.

Q. What is pin and when is it required?

pin is the 6-digit postal PIN code of the party's address. It is available on firstParty and secondParty only.

This field is mandatory for firstParty and secondParty when stateCode is one of two states:

• West Bengal (WB)
• Madhya Pradesh (MP)

NeSL requires the PIN code for address verification in these states as part of the stamp duty registration process. For all other states this field is optional and can be omitted or passed as null. If sent, it must be exactly 6 digits.

Format: exactly 6 digits (e.g., "400001" for Mumbai, "110001" for Delhi).

Q. What is aadhaarVerificationOptions and when should I send it?

aadhaarVerificationOptions is an optional object inside each party (firstParty, secondParty, coBorrowers entries, and guarantor). It is only used when that party's signType includes "Aadhaar". The API does not reject a request that omits it.

NeSL performs a demographic cross-check — it matches the details you send here against the Aadhaar database before it allows the invitee to complete Aadhaar OTP signing. If the details do not match, the signing step is rejected at the NeSL end.

The object contains the following fields:

• verifyInvitee (boolean, optional, default false) — Set to true to enable demographic verification for this party. If false, the other fields are ignored and no cross-check is performed.

• dateOfBirth (string, conditional) — Needed when verifyInvitee is true. Full date of birth of the invitee. Format: YYYY-MM-DD. Example: "1990-07-15". Must match the DOB registered in Aadhaar.

• lastFourDigitOfAadhaar (string, conditional) — Needed when verifyInvitee is true. Last 4 digits of the invitee's Aadhaar number, exactly 4 digits. Example: "4321". NeSL uses this to locate the correct Aadhaar record.

• gender (string, conditional) — Needed when verifyInvitee is true. Gender of the invitee as registered in Aadhaar. Accepted values: "Male", "Female" (letter case is ignored; "M" and "F" are also accepted).

• verifyName (boolean, optional) — Accepted but not applied to NeSL signing; the invitee's name is not verified against Aadhaar. Defaults to false.

Important rules:

• If signType is "Aadhaar" and aadhaarVerificationOptions is null or verifyInvitee is false, NeSL will still allow signing but skips the demographic cross-check. It is strongly recommended to always pass the demographic details when using Aadhaar signing to reduce signing failures.

• When verifyInvitee is true, send dateOfBirth, lastFourDigitOfAadhaar and gender together. The API does not reject a missing value, but the cross-check needs all three.

• The gender field accepts "Male" or "Female" (or "M", "F"). Other values are rejected.

• dateOfBirth must be in strict YYYY-MM-DD format. Passing formats like "15/07/1990" or "July 15 1990" will cause a validation error.

• aadhaarVerificationOptions applies independently to each party. Two parties in the same request can have different signTypes — one using Aadhaar (with demographic options) and another using Electronic (with null options).

Validation Rules for Signing Position Fields

The following validation rules apply to signAppearance, pageToBeSigned, pageNumber, and pageInfo for each party:

Rule 1: At least one positioning method is required. You must provide either signAppearance (a corner like Bottom_Left) or pageInfo (manual coordinates). Both cannot be null at the same time. If you omit signAppearance entirely, it defaults to 3 (Bottom_Left).

Rule 2: signAppearance must be a valid value. If provided, it must be one of: 1 (Top_Left), 2 (Top_Right), 3 (Bottom_Left), 4 (Bottom_Right), or 5 (PageCoordinates). If signAppearance is explicitly null or invalid and pageInfo is also not provided, the request will be rejected.

Rule 3: pageToBeSigned is required unless pageInfo is provided, and it has no default value. You must tell the system which pages to sign (ALL, LAST, FIRST, etc.). If you provide manual pageInfo, pageToBeSigned becomes optional because pageInfo already specifies the pages.

Rule 4: pageToBeSigned must be a valid value. If provided, it must be one of: 1 (FIRST), 2 (LAST), 3 (EVEN), 4 (ODD), 5 (ALL), or 6 (SPECIFY). Invalid values are rejected unless pageInfo is provided as a fallback.

Rule 5: pageNumber is required when pageToBeSigned is SPECIFY and pageInfo is not provided. If you set pageToBeSigned to 6 (SPECIFY), you must provide a comma-separated list of page numbers in pageNumber (e.g., "1,3,7"). You cannot say "specific pages" without telling the system which ones.

Rule 6: pageInfo is required when signAppearance is PageCoordinates. If you set signAppearance to 5 (PageCoordinates), you must provide the pageInfo list with the exact X1, Y1, X2, Y2 coordinates. You cannot select "custom coordinates" without actually providing them.

Summary: pageInfo (manual coordinates) overrides everything. If you provide it, signAppearance and pageToBeSigned become optional. If you do not provide pageInfo, then signAppearance and pageToBeSigned are required and must be valid values.

SignatoriesInfo.SignUrl behaviour

Recommended consumer logic: display the sign link only when signUrl != null AND status != "Signed".