Send a Document for Electronic Signing

Render a signing document and create a REFRACT eSign session to collect electronic signatures from one or more signers via the centrally hosted signing portal.

This tutorial covers the end-to-end flow for collecting electronic signatures on a REFRACT PDF-generated document. Signers receive invitation emails and complete signing through the REFRACT eSign portal, hosted on the REFRACT Platform.

Products used: REFRACT eSign

What You'll Need

A REFRACT PDF licence with the vaultESign feature gate enabled
A PDF template with signature_block nodes defined, one per signer role
Signer email addresses and role names that match the template's signature blocks
The Lifecycle.Reader role on your account if you call as a signed-in user, or the Render.Access application permission on your app if you call with client credentials. Checking signing status needs Lifecycle.Reader either way.

Signature blocks are layout elements

signature_block nodes in a template are layout placeholders that tell REFRACT PDF where to inject the seal image. They are not AcroForm fields. See the Field Manifest reference for details.

Step 1: Render the Document

Render the document using POST /api/render and retain the correlationId, pdfBlobPath, and hash of the rendered PDF - the eSign session request needs the blob path and hash of the exact document being signed.

{
  "templatePath": "templates/vendor-contract.rpkg",
  "correlationId": "ctr-2026-001",
  "documentId": "CTR-2026-001",
  "vendorName": "Contoso Supplies Ltd",
  "contractDate": "2026-05-30"
}

Step 2: Create a Signing Session

POST to /api/esign/session with the correlationId, the rendered PDF's blob path and hash, and one signer entry per slot. Each role must match a signature_block role defined in the PDF template.

POST /api/esign/session
Authorization: Bearer <Entra ID JWT>
Content-Type: application/json

{
  "correlationId": "ctr-2026-001",
  "documentId": "CTR-2026-001",
  "docType": "vendor-contract",
  "pdfBlobPath": "generated-documents/vendor-contract/2026/05/ctr-2026-001.pdf",
  "pdfHash": "sha256:abc123...",
  "signingMode": "sequential",
  "expiresInMinutes": 4320,
  "signers": [
    {
      "slotIndex": 0,
      "role": "vendor",
      "email": "vendor@contoso.com",
      "namePrefill": "Vendor Contact"
    },
    {
      "slotIndex": 1,
      "role": "manager",
      "email": "manager@yourcompany.com"
    }
  ]
}

expiresInMinutes is each signer's window: from 60 to 10080 (7 days), defaulting to 1440 (1 day) on this API when omitted (4320 = 3 days above). A value outside that range is refused with 400. With sequential mode, the vendor receives their invitation first, and the manager is notified only after the vendor completes their slot. Each of them gets the full window from when they are invited.

Signing portal and email delivery

Invitation emails are composed by the REFRACT eSign portal and, by default, sent through REFRACT Shared Services' Azure Communication Services, so there is no email infrastructure to configure in your environment. To send them from your own Azure Communication Services instead, see REFRACT eSign emails. The signing portal is centrally hosted; no portal deployment is required. The portal does keep encrypted signer contact details, OTP hashes, and session state in its own database - see REFRACT eSign for the full data-handling breakdown.

The response returns a groupId and a portalUrl per signer's slot:

{
  "groupId": "grp-xxxx...",
  "expiresAt": "2026-06-02T12:00:00.000Z",
  "slots": [
    { "slotIndex": 0, "sessionId": "sess-xxxx...", "portalUrl": "https://portal.refractplatform.com/sign?t=sess-xxxx...&g=grp-xxxx..." },
    { "slotIndex": 1, "sessionId": "sess-yyyy...", "portalUrl": "https://portal.refractplatform.com/sign?t=sess-yyyy...&g=grp-xxxx..." }
  ]
}

Step 3: Monitor Signing Progress

Query the session state using the correlationId you supplied at creation:

GET /api/esign/session/{correlationId}/status
Authorization: Bearer <Entra ID JWT>

The session moves through pending, in_progress, and sealing to complete as each signer submits their slot.

Step 4: Retrieve the Signed Document

When the session reaches complete, the sealed PDF and evidence certificate are stored in Azure Blob Storage. The evidence certificate contains per-signer records (name, hashed email, IP address, and timestamp), consent statement versions, and the SHA-256 hash of the original rendered PDF.

What Happens Next

The completed signing event is recorded in the REFRACT Lifecycle workspace under the document's correlationId. The Signatures tab shows each signer's slot state, activation time, completion time, and consent records.

To deliver the signed PDF to a third party after completion, call POST /api/delivery once the session reaches complete, using the sealed PDF's blob path.

REFRACT eSign Reference

Full reference for signing modes, slot states, OTP configuration, consent model, and the evidence certificate.

REFRACT eSign Overview Field Manifest Reference