Signature Customization

Full API reference for visible PDF signature appearance — all customization options are supported and production-ready on Mobile App and Desktop Software.

All options supported

Every appearance option listed below is implemented and working in SecureSign Mobile App and Desktop Software. Set visible: true on PDF signing requests and pass the appearance object (or equivalent top-level fields accepted for backward compatibility).

Overview

Signature customization controls the visible stamp drawn on a PDF page before the cryptographic PAdES signature is embedded. It does not change the signing algorithm (still SHA-256 + RSA/EC from the DSC token).

Applies to visible PDF signing only (visible: true).
Invisible PDF signatures ignore appearance fields.
XML and hash signing do not use appearance options.
Coordinates use PDF points (1/72 inch); origin is bottom-left of the page.

Platform Support

Option group	Mobile App	Desktop Software	REST API `POST /sign/pdf`
Text fields (name, designation, labels)	Supported	Supported	Supported
Date & time display	Supported	Supported	Supported
Certificate serial display	Supported	Supported	Supported
Custom text line	Supported	Supported	Supported
Signature image	Supported	Supported	Supported
Company logo	Supported	Supported	Supported
QR code	Supported	Supported	Supported
Custom stamp image	Supported	Supported	Supported
Appearance templates	Supported	Supported	Supported

Request Shape

Pass customization inside an appearance object on PDF sign requests. Top-level aliases (e.g. signerName at root) are also accepted for backward compatibility.

POST https://api.securesign.toolsbots.com/v1/sign/pdf
{
  "pdfBase64": "JVBERi0x...",
  "visible": true,
  "page": 1,
  "position": {
    "x": 72,
    "y": 120,
    "width": 240,
    "height": 90
  },
  "appearance": {
    "templateId": "gov_portal",
    "signerName": "Rajesh Kumar",
    "designation": "Director",
    "reason": "Approved for MCA filing",
    "location": "Mumbai, India",
    "showDateTime": true,
    "showSerial": true,
    "customText": "Digitally signed via SecureSign",
    "imageBase64": "iVBORw0KGgo...",
    "logoBase64": "iVBORw0KGgo...",
    "stampImageBase64": "iVBORw0KGgo...",
    "qrContent": "https://verify.example.gov.in/doc/abc123"
  }
}

Position object

Field	Type	Required	Description
`x`	number	Yes	Left edge in PDF points from page bottom-left
`y`	number	Yes	Bottom edge in PDF points
`width`	number	No	Stamp width in points (default `200`)
`height`	number	No	Stamp height in points (default `72`; increase when using logo + QR)

Appearance Fields

All fields below are optional unless noted. Omitted fields use product defaults or certificate-derived values (e.g. signer name from DSC subject CN).

Text & labels

Field	Type	Default	Description
`signerName`	string	Certificate CN	Name shown on the visible stamp
`designation`	string	—	Job title or role (e.g. `Director`, `Authorized Signatory`)
`customText`	string	—	Free-form line below designation (portal reference, file number, etc.)
`reason`	string	`Document digitally signed`	Signing reason shown on stamp
`location`	string	`India`	Signing location shown on stamp
`signedByLabel`	string	`Digitally signed by`	Header label above signer name
`dateLabel`	string	`Date`	Label prefix for timestamp line
`reasonLabel`	string	`Reason`	Label prefix for reason line
`locationLabel`	string	`Location`	Label prefix for location line

Date, time & certificate

Field	Type	Default	Description
`showDateTime`	boolean	`true`	When `true`, signing timestamp is rendered on the stamp
`dateFormat`	string	`dd MMM yyyy HH:mm:ss z`	Java-style date format for the displayed timestamp
`showSerial`	boolean	`false`	When `true`, DSC certificate serial number is shown

Images, QR & stamp

Field	Type	Default	Description
`imageBase64`	string	—	Custom signature bitmap (PNG or JPEG, base64). Drawn inside the stamp area
`logoBase64`	string	—	Organization logo (PNG or JPEG, base64). Typically top-left or top-right per template
`stampImageBase64`	string	—	Round or square rubber-stamp image (PNG with transparency recommended)
`qrContent`	string	—	URL or text encoded in verification QR code on the stamp
`qrSize`	number	`48`	QR code edge length in PDF points

Legacy alias: stampImage is accepted as an alias for stampImageBase64.

Layout & colors

Field	Type	Default	Description
`templateId`	string	`standard`	Pre-built layout template (see Templates)
`borderColor`	string	`#3366AA`	Stamp border color (hex)
`backgroundColor`	string	`#F2F6FF`	Stamp fill color (hex)
`accentColor`	string	`#1A3366`	Title bar / accent strip color (hex)

Templates

Set appearance.templateId to select a layout. All templates support the same fields; templates control element placement and default sizing.

templateId	Layout	Best for
`standard`	Text block: signed-by label, name, date, reason, location	General business documents
`minimal`	Signer name + date/time only	Compact stamps on forms
`gov_portal`	Logo + text block + QR verification code	MCA, GST, GeM, government portals
`branded`	Logo + signature image + name + designation	Corporate letterheads
`stamp_round`	Custom stamp image overlay + optional serial/date	Traditional round/square rubber stamps
`image_only`	Signature image fills the position rectangle	Hand-drawn signature bitmap only

Recommended sizes

For gov_portal and branded templates, set position.height to at least 90 points when using logo + QR together.

Images & Stamps

Formats: PNG (recommended for logos/stamps with transparency) or JPEG.
Encoding: Raw base64 string — no data:image/png;base64, prefix.
Max size: 512 KB per image after base64 decode.
Resolution: 150–300 DPI source images produce sharp stamps at typical PDF zoom levels.
QR content: HTTPS verification URLs are recommended; max 2,048 characters.

Examples

Standard text appearance (Desktop Software)

const params = new URLSearchParams({
  requestId: crypto.randomUUID(),
  hashBase64: sha256Base64,
  hashAlgo: 'SHA256',
  documentType: 'pdf',
  callbackUrl: 'https://portal.example.gov.in/sign/callback',
  apiKey: 'ss_live_abc123xyz'
});
window.location.href = `securesign://sign?${params}`;
// Add documentBase64, visible, position, appearance to URLSearchParams

curl -X POST https://api.securesign.toolsbots.com/v1/sign/pdf \
  -H 'Authorization: Bearer ss_live_abc123xyz' \
  -H 'Content-Type: application/json' \
  -d '{
    "pdfBase64": "JVBERi0x...",
    "visible": true,
    "page": 1,
    "position": { "x": 72, "y": 120, "width": 220, "height": 80 },
    "appearance": {
      "templateId": "standard",
      "signerName": "Rajesh Kumar",
      "designation": "Director",
      "showDateTime": true
    },
    "callbackUrl": "https://portal.example.gov.in/callback"
  }'

Government portal — logo + QR + serial

{
  "pdfBase64": "JVBERi0x...",
  "visible": true,
  "page": 1,
  "position": { "x": 72, "y": 100, "width": 280, "height": 100 },
  "appearance": {
    "templateId": "gov_portal",
    "signerName": "Rajesh Kumar",
    "designation": "Authorized Signatory",
    "showDateTime": true,
    "showSerial": true,
    "logoBase64": "iVBORw0KGgoAAAANSUhEUg...",
    "qrContent": "https://verify.example.gov.in/doc/abc123",
    "qrSize": 56,
    "customText": "MCA Form filing — Ref: ABC/2026/001"
  }
}

Branded — signature image + company logo

{
  "visible": true,
  "page": 1,
  "position": { "x": 350, "y": 80, "width": 260, "height": 110 },
  "appearance": {
    "templateId": "branded",
    "signerName": "Rajesh Kumar",
    "designation": "Managing Director",
    "imageBase64": "iVBORw0KGgo...",
    "logoBase64": "iVBORw0KGgo...",
    "showDateTime": true,
    "borderColor": "#1E40AF",
    "backgroundColor": "#EFF6FF"
  }
}

Round stamp overlay

{
  "visible": true,
  "page": 1,
  "position": { "x": 400, "y": 200, "width": 120, "height": 120 },
  "appearance": {
    "templateId": "stamp_round",
    "stampImageBase64": "iVBORw0KGgo...",
    "showDateTime": true,
    "showSerial": true,
    "signerName": "Rajesh Kumar"
  }
}

Mobile App — deep link with appearance

Pass appearance fields as URL query parameters (JSON-encoded appearance blob) or individual params:

const appearance = {
  templateId: 'gov_portal',
  signerName: 'Rajesh Kumar',
  designation: 'Director',
  showDateTime: true,
  qrContent: 'https://verify.example.gov.in/abc123'
};
const params = new URLSearchParams({
  requestId,
  pdfUrl: encodeURIComponent(pdfDownloadUrl),
  callbackUrl,
  apiKey,
  visible: 'true',
  page: '1',
  appearance: btoa(JSON.stringify(appearance))
});
window.location.href = `securesign://sign/pdf?`;

Response

Successful PDF signing returns the signed document and metadata about the applied appearance:

{
  "success": true,
  "signedPdfBase64": "JVBERi0x...",
  "signatureField": "Signature1",
  "appearanceApplied": {
    "templateId": "gov_portal",
    "visible": true,
    "page": 1,
    "position": { "x": 72, "y": 100, "width": 280, "height": 100 },
    "signerName": "Rajesh Kumar",
    "signedAt": "2026-06-22T10:30:00+05:30"
  }
}

Errors

Code	Cause	Resolution
`APPEARANCE_REQUIRES_VISIBLE`	`appearance` sent with `visible: false`	Set `visible: true` or remove appearance fields
`INVALID_IMAGE_FORMAT`	`imageBase64`, `logoBase64`, or `stampImageBase64` is not valid PNG/JPEG	Re-encode image; remove data-URI prefix
`IMAGE_TOO_LARGE`	Decoded image exceeds 512 KB	Compress or resize source image
`INVALID_TEMPLATE`	Unknown `templateId`	Use a supported template from the table above
`POSITION_OUT_OF_BOUNDS`	Stamp rectangle extends past page edge	Adjust `position.x`, `y`, `width`, or `height`
`QR_CONTENT_TOO_LONG`	`qrContent` exceeds 2,048 characters	Shorten URL or use a redirect link

See also PDF Signing for multi-page and invisible signature options, and Signing API — POST /sign/pdf for orchestration flow.