Document Signing Overview

What Is eSign?

The Document Signing (eSign) module allows you to create, send, and manage legally-binding electronic signature requests. Common use cases include:

• Client service agreements and contracts.
• Employee offer letters and contracts of employment.
• NDAs and partnership agreements.
• Change request approvals.
• Project sign-off documents.

Key Concepts

Templates

A template is a reusable document with the content pre-set and signature/form fields placed. You create the template once and use it for multiple signing requests.

Signing Requests

A signing request is an instance of a template sent to one or more specific signers. Each signer receives a unique email with a personalised signing link. No login is required to sign.

Signers

Each signing request has one or more signers with a specific sign order. If sign order is enforced, signer 2 only receives their invitation after signer 1 has completed signing.

Creating a Template

1. Go to eSign → Templates.
2. Click + New Template.
3. Give the template a Name (internal reference).
4. Enter the Document Content (HTML body).
5. In the Fields panel, drag field types onto the document:
   • Signature — captures the signer's drawn or typed signature.
   • Text — free-text field (e.g. name, address).
   • Date — pre-filled with today's date or left for the signer.
   • Checkbox — for consent or initials.
6. Assign each field to a Signer.
7. Click Save Template.

Sending a Signing Request

1. Go to eSign → Requests.
2. Click + New Request.
3. Select the Template.
4. Set a Title for this specific request.
5. Add an optional Message shown in the invitation email.
6. Set an optional Expiry Date.
7. Add Signers — name, email, and sign order for each.
8. Click Send. Signer 1 receives an invitation email immediately.

Tracking Status

Status	Description
DRAFT	Not yet sent.
SENT	Invitation sent, awaiting signatures.
PARTIALLY_SIGNED	Some signers completed, others pending.
COMPLETED	All signers have signed. Document stored.
DECLINED	A signer declined. Request cancelled.
EXPIRED	Expiry date passed before completion.

Click a request to see the full audit trail: when each signer viewed, signed, or declined.

API Access (for external workflows)

eSign requests can be created, sent, and tracked from external systems. Common use cases:

• A sales platform pushes a contract for signature when a deal is marked "Won".
• A HR system sends an offer letter the moment a candidate accepts.
• A custom portal lets a customer self-serve a standard agreement.

All endpoints require an authenticated session (Bearer JWT in authorization). Signers themselves never need a portal login — they sign at the public URL /sign/<token> in their browser.

Log in

curl -s -X POST https://portal.kwgroup.org.uk/api/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"ops@yourcompany.com","password":"...","mfaCode":"123456"}' \
  > /tmp/login.json
TOKEN=$(jq -r .accessToken /tmp/login.json)

The accessToken is valid for 15 minutes; refresh via /api/auth/refresh or the refreshToken cookie.

Create + send a signing request

# 1. List templates to find the one you want.
curl -s -H "authorization: Bearer $TOKEN" \
  https://portal.kwgroup.org.uk/api/esign/templates

# 2. Create a request from a template and send immediately.
curl -s -X POST -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "templateId": "<templateId>",
    "title": "Acme — Master Services Agreement",
    "message": "Please review and sign at your convenience.",
    "expiresAt": "2026-07-04T00:00:00Z",
    "signers": [
      { "name": "Jane Doe", "email": "jane@acmecorp.com", "order": 1 },
      { "name": "John Smith", "email": "john@acmecorp.com", "order": 2 }
    ]
  }' \
  https://portal.kwgroup.org.uk/api/esign/requests

The response includes the new request's ID and the public signing URL for each signer (/sign/<token>). Signer 1 is emailed immediately if order: 1; signer 2 only gets their invitation after signer 1 completes.

Check status

curl -s -H "authorization: Bearer $TOKEN" \
  https://portal.kwgroup.org.uk/api/esign/requests/<id>

Returns the current status, the per-signer status, the full audit trail (viewed, signed, declined events with timestamps), and — if COMPLETED — a download URL for the signed PDF.

Webhook for completion (optional)

Configure a webhook URL at Admin → Integrations → eSign to receive a POST when a request reaches a terminal state (COMPLETED, DECLINED, EXPIRED). The webhook payload mirrors the request detail response. Webhooks are HMAC-signed with the eSign integration secret; verify the X-KWG-Signature header on receipt.

The public signer endpoint (/sign/<token>) requires no auth — it accepts the per-signer token from the email link. Do not share the URL outside the intended recipient.