SHCIL eStamp

Table of Contents#

1. Before You Start — Authentication
2. The Two Flows — Pdf Flow vs Template Flow
3. End-to-End Flow at a Glance
4. API 1 — Get Master Details
5. API 2 — Get Template Fields
6. API 3 — Generate E-Stamp
7. Slow Generation and the 202 Response
8. API 4 — Get Procured E-Stamps
9. API 5 — Attach E-Stamp
10. API 6 — Report Execution
11. Webhook Delivery
12. Field Origin Map — Where Every Field Comes From
13. Validation Rules & Limits
14. Error Codes
15. FAQ

Before You Start — Authentication#

Every API call must include these two headers (issued to you during onboarding):

Base path: {BASE_URL}/api/v1/StockHoldingEStamp

All requests and responses are JSON. All responses use a common envelope:

{
  "success": true,
  "statusCode": 200,
  "message": "Success",
  "data": { }
}

Fields with no value are omitted from responses — always code defensively for absent optional fields.

Configure a webhook before you start. The Generate API needs a webhook URL — either sent as webhookUrl on each request, or configured for your app during onboarding. A request with neither is rejected. See Webhook Delivery for why.

The Two Flows — Pdf Flow vs Template Flow#

The Master Details API returns articles in two lists — one per flow — and every article carries an articleType confirming which flow it belongs to:

articleType is only ever SYSTEM or CUSTOM, and it always matches the list the article came from — so you never have to decide what a value means. An article that works with either flow simply appears in both lists under the same articleCode: take it from templateArticles to send fields, or from pdfArticles to send documentInfo.

Rule: documentInfo and fields are mutually exclusive — send exactly one of them.

Which flow should I use?

• You already have the final agreement PDF → Pdf flow. One call and you're done: Generate returns the stamped document.
• You want to procure stamps first and attach them to documents later → Template flow. Generate gives you a stamp certificate (status COMPLETED — procured); when your document is ready, call Attach to merge them (status becomes CONSUMED).

End-to-End Flow at a Glance#

Pdf flow (CUSTOM article) — single call

Template flow (SYSTEM article) — procure now, attach later

Execution reporting. SHCIL requires the execution of every stamped document to be reported back once it has been signed. If you sign through the SignCare eSign API this happens automatically — see API 6 — Report Execution for when you would call it yourself.

API 1 — Get Master Details#

GET /api/v1/StockHoldingEStamp/master-details

What it is: The starting point of every integration. Returns the reference data you need before generating any stamp.

Why you need it: The Generate API only accepts state codes and article codes from this list, and checks your stamp duty, consideration price and parties against the limits returned here. Calling Generate with values not present here is rejected.

When to call it: Once at integration time to build your state/article dropdowns, then refresh periodically (the data rarely changes — daily refresh is more than enough).

states[] — the states supported for SHCIL stamping:

templateArticles[] and pdfArticles[] — the articles available in those states, one list per flow. Both use the same shape:

Important: articleCode values are unique per state, not globally. Always pick the article for the same stateCode you intend to stamp in.

Tip: several articles can share one articleNumber and articleName — e.g. a state's Affidavit article covers many templates. Each still has its own articleCode; send the articleCode of the exact entry you want. In templateArticles, articleDescription carries the template name to help you choose.

What the stamp-duty fields mean for your Generate request:

Example response (trimmed):

{
  "success": true,
  "statusCode": 200,
  "message": "Success",
  "data": {
    "states": [
      { "stateName": "Assam", "stateCode": "AS" },
      { "stateName": "Karnataka", "stateCode": "KA" }
    ],
    "templateArticles": [
      {
        "stateCode": "AS",
        "articleNumber": "4",
        "articleCode": 19,
        "articleDescription": "Affidavit - Bharat Gas",
        "articleName": "Affidavit",
        "minDuty": "10",
        "maxDuty": "100",
        "articleType": "SYSTEM",
        "stampDutyType": "STAMP_DUTY_RANGE",
        "considerationPercentage": "0",
        "bothPartyRequired": false
      },
      {
        "stateCode": "AS",
        "articleNumber": "4",
        "articleCode": 20,
        "articleDescription": "Affidavit - Domicile",
        "articleName": "Affidavit",
        "minDuty": "10",
        "maxDuty": "100",
        "articleType": "SYSTEM",
        "stampDutyType": "STAMP_DUTY_RANGE",
        "considerationPercentage": "0",
        "bothPartyRequired": false
      }
    ],
    "pdfArticles": [
      {
        "stateCode": "KA",
        "articleNumber": "6(2)(i)",
        "articleCode": 286,
        "articleDescription": "Pawn or pledge - loan between Rs.1 lakh and Rs.10 lakh",
        "articleName": "Pawn or pledge - loan between Rs.1 lakh and Rs.10 lakh",
        "minDuty": "500",
        "maxDuty": "5000",
        "articleType": "CUSTOM",
        "stampDutyType": "CONSIDERATION_PRICE",
        "considerationPercentage": "0.5",
        "minConsiderationPrice": "100001",
        "maxConsiderationPrice": "1000000",
        "bothPartyRequired": true
      }
    ]
  }
}

Note how the two template-flow rows share articleNumber "4" and articleName "Affidavit" — only articleCode (and the template name in articleDescription) differs. That is the normal case, not an edge case.

API 2 — Get Template Fields#

GET /api/v1/StockHoldingEStamp/template/fields/{articleCode}

What it is: Returns the dynamic fields of a document template.

Why you need it: In the template flow the document is generated from a SHCIL template — you must supply values for the template's fields. This API tells you which fields exist, their ids, types, and validation rules.

When to call it: Template flow only, after the user picks a SYSTEM article from the Master Details response. Skip it entirely in the pdf flow.

Path parameter: articleCode (required, positive integer) — from templateArticles[].articleCode of the Master Details API.

props (each key omitted when not applicable):

Send dates in dd/MM/yyyy format, and no earlier than the field's minDate.

API 3 — Generate E-Stamp#

POST /api/v1/StockHoldingEStamp/generate

What it is: The core API — generates the e-Stamp certificate. In the pdf flow it also applies the certificate to your document in the same call.

When to call it: After you've chosen the state + article from Master Details (and collected field values via Template Fields, if template flow).

Example request — Pdf flow (a CONSIDERATION_PRICE article):

{
  "referenceId": "LOAN-2026-000123",
  "selfReportExecution": false,
  "documentInfo": {
    "name": "Loan Agreement.pdf",
    "content": "<base64>"
  },
  "firstParty": { "name": "Rahul Sharma", "pan": "ABCDE1234F", "mobile": "9876543210" },
  "secondParty": { "name": "Acme Finance Ltd", "pan": "AABCA9876B", "mobile": "9123456780" },
  "stampDetails": {
    "stateCode": "KA",
    "articleCode": 286,
    "stampDutyAmount": 2500,
    "stampDutyPaidBy": "Rahul Sharma",
    "considerationPrice": 500000,
    "documentDescription": "Loan agreement between Rahul Sharma and Acme Finance Ltd"
  },
  "webhookUrl": "https://yourapp.com/webhooks/estamp"
}

Example request — Template flow (a STAMP_DUTY_RANGE article):

{
  "referenceId": "AFF-2026-000124",
  "fields": [
    { "id": "1024", "value": "Rahul Sharma" },
    { "id": "1025", "value": "Guwahati" }
  ],
  "firstParty": { "name": "Rahul Sharma", "mobile": "9876543210" },
  "stampDetails": {
    "stateCode": "AS",
    "articleCode": 19,
    "stampDutyAmount": 100,
    "stampDutyPaidBy": "Rahul Sharma"
  },
  "webhookUrl": "https://yourapp.com/webhooks/estamp"
}

Response (HTTP 200)

This API can also return HTTP 202 — when generation is taking longer than usual, or always when you send isAsync: true — see Slow Generation and the 202 Response below. When that happens, eStampId, documentId, userDocumentId, and every certificate field above are absent (not yet created) — only referenceId, reconMappingId and status: "ACCEPTED" are present.

Charges: stamp duty and applicable charges are deducted from your SHCIL eStamp wallet when the stamp is generated. A request is refused up front if your wallet balance cannot cover it.

Slow Generation and the 202 Response#

Generate normally answers synchronously — SHCIL almost always responds within seconds. Occasionally SHCIL's own platform is slower than usual. Rather than holding your connection open indefinitely, if the certificate isn't ready within the sync wait window (server-configured, currently ~40 seconds), the API responds immediately with:

{
  "success": true,
  "statusCode": 202,
  "message": "Accepted. Generation is taking longer than usual — the result will be delivered to your webhookUrl. Do not retry this referenceId.",
  "data": {
    "referenceId": "LOAN-2026-000123",
    "reconMappingId": "SC0000000000000ABCDE",
    "status": "ACCEPTED"
  }
}

202 is a normal response, not an error. During a slow spell it can be the outcome for most or all of your requests, not a rare edge case — don't treat it as a failure path you can skip building.

What happens next: the certificate is still being generated in the background. Once it finishes (success or failure), the outcome is delivered to your webhook — the same payload shape as the 200 response on success (see Webhook Delivery below for the failure shape). There is currently no separate "check status" endpoint — the webhook is the only delivery channel for a 202, which is why a webhook is required.

The one rule that matters — do not retry the same operation:

Calling again with a new referenceId while the original is still processing does not cancel or replace it — it starts a second, independent generation and, if both succeed, you pay for both. The only safe move while a referenceId is in flight is to wait.

Asking for the 202 on purpose — isAsync#

If you would rather not hold the connection at all — because you handle every result on your webhook, or to test your own 202 handling — send isAsync: true on the Generate request. The default is false, and then everything above stays exactly as it is.

How it behaves with isAsync: true:

1. The request is validated first. Missing fields, a wrong article, an insufficient wallet, an unsupported state and similar problems are still returned immediately as the usual 4xx — nothing is accepted.

2. If it is valid, you get 202 at once:

   {
     "success": true,
     "statusCode": 202,
     "message": "Accepted. As requested (isAsync), the stamp is generated in the background and the result will be delivered to your webhookUrl. Do not retry this referenceId.",
     "data": {
       "referenceId": "LOAN-2026-000123",
       "reconMappingId": "SC0000000000000ABCDE",
       "status": "ACCEPTED"
     }
   }

   Copy

3. The stamp is generated in the background, and the outcome is POSTed to your webhook — the same success payload as the 200 response, or the failure payload described in Webhook Delivery.

4. A webhook is needed — send webhookUrl or have one configured for your app, as for every Generate request.

5. Do not send the same referenceId again. While it is still being processed it just returns the same 202; once it has finished it is rejected as already used.

The 202 itself is identical to the "slow SHCIL" one described above, so one piece of code handles both: on a 202, store the referenceId and wait for the webhook.

When SHCIL has not finished the stamp — status: "PENDING"#

Occasionally SHCIL creates the document but does not finish the eStamp (SHCIL statuses ESTAMP_PENDING or ERROR_IN_PDF_GENERATION). SignCare then completes it for you automatically by regenerating it with SHCIL — SHCIL does not charge again for this. You get:

{
  "success": true,
  "statusCode": 202,
  "message": "eStamp is being completed by SHCIL. The result will be delivered to your webhookUrl. Do not retry this referenceId — you have not been charged yet.",
  "data": {
    "referenceId": "LOAN-2026-000123",
    "reconMappingId": "SCAB12CD34EF56GH78IJ",
    "eStampId": "3f2a9c1e-5b7d-4e2a-9f10-2c3d4e5f6a7b",
    "userDocumentId": 45237,
    "status": "PENDING"
  }
}

• You are not charged until the stamp is ready.
• When it is ready, the normal success webhook is sent (same payload as for a 202 above), and the stamp appears in Get Procured E-Stamps.
• If SHCIL cannot complete it after several automatic attempts, the failure webhook is sent and you are never charged for it.
• Do not retry — the same referenceId is rejected, and a new referenceId would make SHCIL issue (and charge) a second stamp.

API 4 — Get Procured E-Stamps#

POST /api/v1/StockHoldingEStamp/procured

What it is: Your stamp inventory — every e-Stamp procured via the template flow with the Generate API that has not yet been attached to a document, newest first.

Why you need it: In the procure-now-attach-later model this is your source of truth. Use it to build a "pick a stamp" screen, reconcile what you've paid for, or recover an eStampId you didn't store.

When to call it: Any time between Generate and Attach.

Request body — optional filters. Send {} (or no body) to get everything:

Response fields

Example request:

{ "stateCode": "DL" }

Example response:

{
  "success": true,
  "statusCode": 200,
  "message": "Success",
  "data": {
    "count": 1,
    "stamps": [
      {
        "eStampId": "42bf8e05-7823-47f0-92b8-c997cac919e2",
        "userDocumentId": 80832,
        "reconMappingId": "SC641A5I2MR42I9NJ57L",
        "status": "COMPLETED",
        "certId": "IN-DL68613570100523Y",
        "urn": "DL1007DIGID2026217795031DLJN",
        "certificateIssuedDate": "05-Aug-2026 04:27 PM",
        "articleName": "Loan Agreement Title Deed",
        "stampDetails": { "stateCode": "DL", "articleCode": 1007, "stampDutyAmount": 100, "stampDutyPaidBy": "Acme Pvt Ltd" },
        "firstParty": { "name": "Acme Pvt Ltd", "mobile": "9876543210" },
        "createdOn": "2026-08-05T10:57:04Z",
        "base64FileData": "<the stamp's certificate PDF>"
      }
    ]
  }
}

A stamp disappears once attached. After a successful Attach the stamp becomes CONSUMED and drops out of this list — so what you see here is always safe to attach.

Response size: every entry carries its certificate PDF. If you hold many un-attached stamps, use the stateCode or estampIds filter to fetch only what you need.

API 5 — Attach E-Stamp#

POST /api/v1/StockHoldingEStamp/attach

What it is: Attaches a procured e-Stamp (template flow) onto your own PDF — the certificate pages are merged with your document, producing the final stamped document.

Why you need it: Completes the template flow. Duty was already paid at generation — no additional stamp duty is charged here.

When to call it: After template-flow Generate, whenever your final document is ready.

Response (HTTP 200)

Each e-Stamp can be attached exactly once. After a successful attach its status becomes CONSUMED and it disappears from the Procured list. A second attempt is rejected with "This eStamp has already been attached to a document."

API 6 — Report Execution#

POST /api/v1/StockHoldingEStamp/consume/report

What it is: Tells SHCIL that a stamped document has been executed (signed by its parties) — the document reference and how many people signed it. SHCIL requires this for every stamp.

Do you need to call it? Usually not:

Call it yourself when the exact signing date or signatory count matters to you, or when only you know when signing finished.

Request

The signatory counts apply to every id in userDocumentIds.

Example request:

{
  "userDocumentIds": [80832],
  "executionDateTime": "27/07/2026 14:30:00",
  "noOfSignatories": 2,
  "noOfDigitalSignatures": 0,
  "noOfElectronicSignatures": 2
}

Response

• One id sent → data.message: SHCIL's confirmation. An id that is not found (or not yours) returns HTTP 404.
• Several distinct ids sent → data.results[]: one entry per id, so one bad id never hides the others. HTTP 200 when all succeed, 207 when any failed.

Safe to repeat. A stamp whose execution was already reported — by you, by SignCare eSign, or by the automatic report — is returned as successful with "Execution was already reported for this stamp." It is never filed with SHCIL twice.

Webhook Delivery#

SignCare POSTs the outcome of every Generate request to your webhook as JSON — the webhookUrl on the request, or the webhook configured for your app if the request has none. This is not just a courtesy notification — for any request that returned HTTP 202 (see Slow Generation and the 202 Response), the webhook is the only place the outcome is delivered, which is why a webhook is required.

Success payload — the same fields as the Generate response:

{
  "success": true,
  "statusCode": 200,
  "message": "Success",
  "data": {
    "referenceId": "LOAN-2026-000123",
    "eStampId": "0d1f7f5e-…",
    "documentId": "8c2a41d9-…",
    "userDocumentId": 123456,
    "reconMappingId": "SC0000000000000ABCDE",
    "status": "COMPLETED",
    "certId": "IN-AS12345678901234X",
    "urn": "…",
    "certificateNo": "…",
    "certificateIssuedDate": "10-Jul-2026 11:42:05",
    "base64FileData": "<base64 PDF>"
  }
}

Failure payload — sent when a 202 request ultimately fails (nothing was created and nothing was charged in this case):

{
  "success": false,
  "statusCode": 422,
  "message": "eStamp generation failed. Please try again.",
  "data": {
    "referenceId": "LOAN-2026-000123",
    "status": "FAILED",
    "errorMessage": "eStamp generation failed. Please try again."
  }
}

On failure, eStampId/documentId/userDocumentId/certificate fields are all absent — nothing was generated. Read errorMessage, fix whatever it describes, and retry with a new referenceId.

Notes:

• The PDF arrives as base64, unless your account is set up to receive webhooks without file content.
• Use an HTTPS URL for webhookUrl.
• Respond with HTTP 2xx to acknowledge. Failed deliveries are retried, so treat deliveries as at-least-once and de-duplicate on referenceId/eStampId.

Field Origin Map — Where Every Field Comes From#

And where response fields go next:

Validation Rules & Limits#

Error Codes#

Every error uses the standard envelope, with a plain-English message naming the problem:

{
  "data": null,
  "messages": [],
  "request_id": null,
  "success": false,
  "statusCode": 400,
  "message": "Consideration price must be between 100001 and 1000000 for article 'Pawn or pledge - loan between Rs.1 lakh and Rs.10 lakh'."
}

Common validation messages:

Safe retry rule — read this before wiring up automatic retries. Not every non-200 means nothing happened:

• 400 / 401 / 402 / 429 — nothing was created, safe to fix-and-retry with a new referenceId.
• 500, or no response at all (a client-side timeout) — the request may have already succeeded on our side before your connection dropped or timed out. Blindly retrying with a new referenceId can create — and charge for — a second stamp for a request that actually went through. Before retrying, check whether the original referenceId already produced a result (a webhook that arrived late, or Get Procured E-Stamps for the template flow) rather than assuming it failed.
• 202 is not in either bucket — it is not a failure at all. See the row above.

This is exactly why referenceId exists: reconcile on it before you resend the same operation.

FAQ#

Q. Does the Generate API also get the document signed? No. Generation and signing are separate. Generate only produces the stamped document; to collect signatures, pass the returned documentId to the eSign API.

Q. Is eSign mandatory to procure a stamp? No. A stamp is procured — valid and charged — as soon as Generate returns success. eSign is how the document gets signed; when it is signed through SignCare eSign, execution is also reported to SHCIL automatically.

Q. Do you send document links in responses or webhooks? No — the document is always delivered inline as base64FileData. Nothing is exposed via public links.

Q. Can I attach one e-Stamp to multiple documents? No. One e-Stamp = one document. After attach, the stamp is CONSUMED.

Q. Can I reuse a referenceId? Never. It's your idempotency/correlation key — one per request, across Generate and Attach alike.

Q. How do I know whether considerationPrice is required? Check the article's stampDutyType in Master Details. For CONSIDERATION_PRICE it is required and must sit between minConsiderationPrice and maxConsiderationPrice. For any other type it is optional.

Q. When do I need to send both parties? When the article has bothPartyRequired: true — both firstParty and secondParty, each with name and mobile. Otherwise one party is enough, as long as stampDutyPaidBy names a party you sent.

Q. Do I have to call the Report Execution API? Only if you sign outside SignCare and set selfReportExecution: true on Generate. Signing through SignCare eSign reports automatically, and with the default selfReportExecution: false SignCare reports for you after a grace period.

Q. Do I have to store eStampId myself? It's recommended, but not required — anything procured and not yet attached is always retrievable from Get Procured E-Stamps.

Q. The articleCode I used worked for one state but is rejected for another. Why? Article codes are unique per state. The same numeric code can mean a different article in another state — always select the article entry matching your stateCode.

Q. Several articles have the same name. Which one do I pick? Many entries share one legal article (articleNumber and articleName). Each has its own articleCode — that is what identifies the exact entry. Send the articleCode of the one you want.

Q. What is reconMappingId for? It's an auto-generated correlation key tied to the stamp. Quote it (along with referenceId) in any support or reconciliation conversation.

Q. Which states/articles are supported? Whatever the Master Details API returns — it is the live source of truth. Don't hardcode the lists.

Q. I got a 202. Did my request fail? No — 202 means it's still processing, not that it failed. It happens when generation is taking longer than usual, or always when you sent isAsync: true. Wait for the webhook; don't retry the same referenceId. See Slow Generation and the 202 Response.

Q. What does isAsync do, and should I use it? It is optional and defaults to false (the API waits up to ~40 seconds and answers with the stamp). Set it to true if you want an immediate 202 and prefer to receive every result on your webhook — or to test your 202 handling. It needs a webhook. Request errors are still returned immediately as 4xx. See Asking for the 202 on purpose.

Q. My request timed out on my end (or I never got a response) — is it safe to retry? Not automatically. Unlike a clean 400/401/402/429, a timeout or a 500 doesn't tell you whether the stamp was actually generated on our side before your connection dropped. Check the webhook or Get Procured E-Stamps for that referenceId first — if it already succeeded, retrying with a new referenceId creates and charges for a second stamp.

Q. Is a webhook actually required? Yes — either webhookUrl on the request or a webhook configured for your app. It is the only delivery channel when a request returns 202; there is no separate status-check API.