E-Signature

The signature object adds a cryptographic digital signature to the generated PDF. Signatures provide non-repudiation and tamper detection — any modification to the signed PDF invalidates the signature.

Properties

Property	Type	Default	Description
fieldName	string	—	Name of the signature form field
position	object	—	Fixed position on the page (see below)
appearance	object	—	Visual appearance of the signature block
signatureCreator	string	—	Application name recorded as the signature creator
signingType	string	"PAdES"	Signing standard: PAdES or Detached
certificate	string	—	Path to the PKCS#12 (.p12/.pfx) certificate file
password	string	—	Password for the certificate file
contact	string	—	Contact information for the signer
timestampServer	string	—	URL of an RFC 3161 timestamp authority (optional)
visible	boolean	true	Whether the signature block is visible on the page
claimedSignDate	string	current time	Date string in yyyy.MM.dd HH:mm:ss K format
certificationLevel	string	"NO_CHANGES_PERMITTED"	What modifications are allowed after signing
fieldLock	object	—	Lock specific form fields after signing
style	string	—	Named style reference for the signature appearance

Signing types

Type	Description
PAdES	PDF Advanced Electronic Signature — embedded in the PDF per ETSI EN 319 142. Recommended for most use cases.
Detached	Detached CMS/CAdES signature — the signature is a separate CMS object. Used when interoperability with non-PDF systems is needed.

Position

The position object places the visible signature block at a fixed location.

Property	Type	Default	Description
pageNumber	number	1	1-based page number
left	number	100	Distance from the left edge in points
bottom	number	150	Distance from the bottom edge in points
width	number	160	Width of the signature block in points
height	number	50	Height of the signature block in points

Appearance

The appearance object controls what is displayed in the visible signature block.

Property	Type	Description
signedBy	string	Name of the signer displayed in the block
signDate	string	Date string displayed in the block
reason	string	Reason for signing (e.g., "Approved", "Reviewed")
location	string	Location of the signer (e.g., "Portland, OR")
image	object	Optional image (e.g., scanned signature) with src, width, height

Certification levels

Level	Description
NO_CHANGES_PERMITTED	No modifications allowed after signing
FORM_FILLING	Only form field filling is allowed
FORM_FILLING_AND_ANNOTATION	Form filling and annotations are allowed

Field lock

The fieldLock object restricts form field modifications after signing.

Property	Type	Description
lockPermissions	string	FORM_FILLING or FORM_FILLING_AND_ANNOTATION
fieldLockAction	string	ALL (lock all fields) or INCLUDE/EXCLUDE with lockedFields
lockedFields	string[]	Names of specific fields to lock or exclude from locking

Examples

Basic visible signature

{
  "document": {
    "signature": {
      "fieldName": "approval_sig",
      "certificate": "/certs/signer.p12",
      "password": "certPassword",
      "signingType": "PAdES",
      "signatureCreator": "DocPayload",
      "contact": "legal@company.com",
      "visible": true,
      "position": {
        "pageNumber": 1,
        "left": 350,
        "bottom": 50,
        "width": 200,
        "height": 60
      },
      "appearance": {
        "signedBy": "Lisa Thompson",
        "reason": "Approved",
        "location": "Portland, OR"
      }
    },
    "content": [
      { "p": "This document has been reviewed and approved." }
    ]
  }
}

Invisible signature

{
  "document": {
    "signature": {
      "fieldName": "integrity_sig",
      "certificate": "/certs/system.p12",
      "password": "systemPass",
      "signingType": "PAdES",
      "signatureCreator": "DocPayload",
      "visible": false,
      "certificationLevel": "NO_CHANGES_PERMITTED"
    },
    "content": [
      { "p": "This document is digitally signed for integrity verification." }
    ]
  }
}

Signature with timestamp server

{
  "document": {
    "signature": {
      "fieldName": "timestamped_sig",
      "certificate": "/certs/signer.p12",
      "password": "certPassword",
      "signingType": "PAdES",
      "signatureCreator": "DocPayload",
      "timestampServer": "http://timestamp.digicert.com",
      "visible": true,
      "position": {
        "pageNumber": 1,
        "left": 50,
        "bottom": 50,
        "width": 200,
        "height": 60
      },
      "appearance": {
        "signedBy": "Automated System",
        "reason": "Generated and signed",
        "location": "Cloud"
      }
    },
    "content": [
      { "p": "Signed with a trusted timestamp for long-term validation." }
    ]
  }
}

Signature with field locking

{
  "document": {
    "signature": {
      "fieldName": "final_approval",
      "certificate": "/certs/approver.p12",
      "password": "approverPass",
      "signingType": "PAdES",
      "signatureCreator": "DocPayload",
      "certificationLevel": "FORM_FILLING",
      "fieldLock": {
        "lockPermissions": "FORM_FILLING",
        "fieldLockAction": "ALL",
        "lockedFields": []
      },
      "visible": true,
      "position": {
        "pageNumber": 1,
        "left": 350,
        "bottom": 50,
        "width": 200,
        "height": 60
      },
      "appearance": {
        "signedBy": "Final Approver",
        "reason": "Final approval — all fields locked",
        "location": "Head Office"
      }
    },
    "content": [
      { "p": "After signing, no form fields can be modified." }
    ]
  }
}