Template Management API

Choosing an endpoint#

Template render — when the document is the deliverable#

Statements, receipts, certificates, sanction letters, filled-in forms — anything you are going to store, email or hand to a customer yourself. You send a template id and field values, you get a PDF back, and that is the whole interaction. No signer information is accepted and none is needed.

Template + Signer — when the document has to be signed#

preview renders the document so you (or your user) can check it before committing. request then fills the same template, creates a document in your SignCare account, attaches the signers you name, and starts the signing workflow. Use these two together whenever a signature — Aadhaar, DSC or electronic — is the point.

Template + eStamp + Signer — when the document needs a SHCIL stamp#

Some agreements must carry a SHCIL e-stamp before they are signed. Send the same POST /api/v1/Template/request you already use, and add a shcilStampInfo block. SignCare then buys the stamp, places it in the document, creates the signing document and invites the signers — in one request.

The call waits up to about 40 seconds for the stamp and the signing document:

• Ready in time: the result comes back in the same response (200 OK).
• Not ready in time: you get 202 Accepted and collect the result from the status API.
• Webhook (optional): if you give a responseUrl, or one is configured for your account, the result is also delivered there.

Request#

{
  "referenceId": "AGREEMENT-2026-0001",
  "templateId": "8f14e45f-ceea-467a-9f0a-1c2b3d4e5f60",
  "documentName": "Service Agreement",
  "signers": [
    {
      "userId": "d45cdb43-36d9-425f-8755-cd8432ca0968",
      "name": "Rahul Patel",
      "emailId": "rahul@example.com",
      "mobileNo": "9876543210",
      "signType": "Aadhaar",
      "order": 1
    },
    {
      "userId": "51456781-ec6f-4c11-ae59-3160f64beac6",
      "name": "Meera Shah",
      "emailId": "meera@example.com",
      "signType": "Electronic",
      "order": 2
    }
  ],
  "fields": [
    { "displayName": "Party Name", "required": false, "type": "Text", "fieldName": "{{var_PartyName}}", "fieldValue": "Rahul Patel" }
  ],
  "shcilStampInfo": {
    "firstPartyName": "Rahul Patel",
    "firstPartyMobile": "9876543210",
    "firstPartyPan": "ABCDE1234F",
    "secondPartyName": "Meera Shah",
    "secondPartyMobile": "9876543211",
    "stateCode": "AS",
    "articleCode": 42,
    "stampDutyAmount": 100,
    "stampDutyPaidBy": "Rahul Patel",
    "documentDescription": "Service Agreement"
  },
  "responseUrl": "https://your-server.example.com/signcare/callback"
}

referenceId — your own id for this request, 1 to 64 letters, digits, hyphens or underscores. It can be used once. A request that failed before a stamp was issued can be sent again with the same id.

signers[].userId — the signer position in the template, as returned by GET /api/v1/Template/get. Each position can be used only once.

responseUrl — optional. If you give one (or a webhook URL is configured for your account), the result is also delivered there. Without a webhook, use the response of this call or the status API.

Choosing the state and the article#

Take both values from the SHCIL Master Details API, GET /api/v1/StockHoldingEStamp/master-details. Its response has three lists:

1. Call the Master Details API.
2. Choose the state from states.
3. In pdfArticles, find the rows whose stateCode is that state and choose the article you need.
4. Send that row's stateCode and articleCode in shcilStampInfo, exactly as listed. Another code that belongs to the same article, but is not listed in pdfArticles, is not accepted.

The same row tells you the rules for the rest of the request:

{
  "stateCode": "AS",
  "articleCode": 42,
  "articleName": "Agreement or Memorandum of an agreement - Agreements other than applicable under 5(a) and 5(b)",
  "minDuty": "100.0",
  "articleType": "CUSTOM",
  "bothPartyRequired": true
}

The Master Details API needs the SHCIL eStamp API to be enabled for your account. If it is not, the call is refused and you cannot look up articles.

Everything is checked before a stamp is bought#

A request that fails any of these checks is rejected immediately with an error, and nothing is charged and no stamp is bought.

The response#

How the call ends depends on how long the stamp takes:

The 202 Accepted response:

{
  "data": {
    "documentReferenceId": "AGREEMENT-2026-0001",
    "reconMappingId": "SCABCDEFGHIJKLMNOPQR",
    "status": "ACCEPTED"
  },
  "success": true,
  "statusCode": 202,
  "message": "Accepted. eStamp generation is taking longer than usual — fetch the stamped document and eSign links from the Template request status API using this referenceId. Do not retry this referenceId."
}

Keep documentReferenceId and reconMappingId; either one identifies this request later. Sending the same referenceId again while it is in progress waits for that same request and returns its result, or this same 202. It does not create a second stamp.

The result#

The result body is the same in all three places: the 200 response, the status API and the webhook.

A webhook is an HTTP POST, and the x-signcare-event header tells you which result it is:

When it succeeded

{
  "data": {
    "documentId": "01a13924-c53e-7730-a227-e04af1adfa17",
    "documentReferenceId": "AGREEMENT-2026-0001",
    "responseTimeStamp": "14-10-2026 06:41:13",
    "userInfo": [
      {
        "userRefId": "d45cdb43-36d9-425f-8755-cd8432ca0968",
        "userId": "fa6f7481-e512-44a5-a969-81392925de96",
        "docSignerId": "d0e36467-ee3c-4766-982d-df654591851f",
        "esignLink": "https://sign.example.com/sign/d0e36467-ee3c-4766-982d-df654591851f/rahul@example.com"
      },
      {
        "userRefId": "51456781-ec6f-4c11-ae59-3160f64beac6",
        "userId": "e21be59a-19c0-44de-b841-92fe48e3283d",
        "docSignerId": "892e587c-f847-4e04-984c-d2a493782459",
        "esignLink": "https://sign.example.com/sign/892e587c-f847-4e04-984c-d2a493782459/meera@example.com"
      }
    ],
    "uiModeURL": "",
    "stampDetails": {
      "eStampId": "943cdb8f-7ae2-4005-99c5-282de8cb7282",
      "reconMappingId": "SCABCDEFGHIJKLMNOPQR",
      "userDocumentId": 120886,
      "certId": "IN-AS00363558894070Y",
      "urn": "AS1004DIGID2026287376478ASAC",
      "certificateNo": "IN-AS00363558894070Y",
      "certificateIssuedDate": "14-Oct-2026 12:11 PM"
    }
  },
  "success": true,
  "statusCode": 200
}

The signers also receive their signing link by email or SMS. Later signing updates for the same document (signed, rejected, expired) are delivered through the usual eSign webhook.

When it failed

{
  "data": {
    "documentReferenceId": "AGREEMENT-2026-0001",
    "reconMappingId": "SCABCDEFGHIJKLMNOPQR",
    "status": "FAILED"
  },
  "success": false,
  "statusCode": 400,
  "message": "Insufficient StockHolding wallet balance. The stamp was not generated and nothing was charged. Recharge the wallet and submit the request again."
}

message gives the reason. If the stamp had already been issued before the failure, data.stampDetails is included — quote it to support so the stamp can be recovered. Otherwise nothing was charged, and you can send the request again with the same referenceId. Once a stamp has been issued, that referenceId cannot be reused.

Checking a result — POST /api/v1/Template/request/status#

Use this API when the call returned 202, or when you do not use a webhook. It returns the same body that the 200 response carries, or that would be sent to your responseUrl.

• It answers 200 for a finished request, including a failed one. Read success and statusCode in the body.
• Suggested schedule after a 202: after 30 seconds, 1 minute and 5 minutes, then every 15 minutes.
• It is free, and it only shows requests made with your own account.

{
  "documentReferenceId": "AGREEMENT-2026-0001"
}

Send documentReferenceId, reconMappingId, or both. If you send both they must belong to the same request.

A request that has been found always answers with a successful lookup. For a request that failed, the failure code and the reason are in the response body, not in the HTTP status.

The documentId in a successful response is the id you need for the other eSign APIs, such as POST /api/v1/esign/status.

If the result has not arrived after a few minutes, check the status. A suggested schedule is after 30 seconds, 1 minute and 5 minutes, then every 15 minutes.

Billing and wallets#

Keep enough balance for the stamp and for any earlier stamps still in progress. A request is rejected if the wallet cannot cover them.

Things to know#

• A stamp that SHCIL has not completed yet keeps the request in progress. The signing document is created automatically when SHCIL completes the stamp, and the result is then delivered.
• Do not submit the same referenceId again while a request is in progress. Wait for the result, or check the status.
• Party names accept English letters and spaces only, because SHCIL does not accept special characters.

Rendering a document#

{
  "templateId": "8f14e45f-ceea-467a-9f0a-1c2b3d4e5f60",
  "documentName": "Sanction Letter - Rahul Patel",
  "fields": [
    { "displayName": "Borrower Name", "fieldName": "borrower_name", "type": "text", "fieldValue": "Rahul Patel" },
    { "displayName": "Sanction Amount", "fieldName": "sanction_amount", "type": "number", "fieldValue": "450000" },
    { "displayName": "Sanction Date", "fieldName": "sanction_date", "type": "date", "fieldValue": "2026-08-26" }
  ]
}

data in the response is the finished PDF, base64-encoded. Decode it and write it to a file — there is nothing further to poll or fetch.

templateId — required. The template id (GUID) from GET /api/v1/Template/get, which also returns each template's field definitions so you know what to send.

documentName — optional. Names the generated PDF; defaults to the template's own name.

fields — required, with at least one entry, when the template declares fields. Copy each field's displayName, fieldName and type exactly as returned by GET /api/v1/Template/get, and add fieldValue. All three are required on every entry; a request that leaves one out is rejected with a 400. The value is placed in the document by fieldName; the required-field and type checks use displayName. Matching is case-insensitive. You may leave out optional fields. (request is stricter — it expects one entry for every field the template declares.)

Send fieldValue as a string. Date values must parse as a date (for example 2026-08-26) and number values as a number (for example 450000).

Field values are validated#

A field declared as date must parse as a date, a field declared as number must parse as a number, and a field marked required must carry a non-empty value. If any of these fail you get a 400 naming the field, and the call is not charged.

Billing#

render is charged as a Template API call — the same rate as /Template/request. Rendering a PDF and creating a full signature request cost the same. Budget accordingly if you are generating documents in volume.

You are charged only when a PDF is actually produced. None of these cost anything:

• a validation error on your field values (400)
• a template id that does not exist (404)
• an insufficient wallet balance (402)

Limits#

render is rate limited to 50 requests per minute per API key + IP. Large templates take longer to render than small ones; a request is answered when the PDF is complete, so allow a generous client-side timeout for long documents.