E-Signature

The signature object adds a cryptographic digital signature to the generated PDF and DOCX. Signatures provide non-repudiation and tamper detection: any modification to the signed file 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	—	The signing key: a PKCS#12 (.p12/.pfx) file by its path (`certs/signer.p12`), or the name of a key you keep in your own vault (`contracts`). Required
`password`	string	—	Password for the certificate file; absent or empty is the empty password. A key in your own vault takes none
`contactInfo`	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	build time	The signing time the signer asserts, as an ISO 8601 date and time (`2026-09-01T14:30:00Z`)
`digest`	string	`"sha256"`	The digest the signature is computed over: `sha256`, `sha384` or `sha512`
`certificationLevel`	string	`"noChanges"`	What modifications are allowed after signing
`fieldLock`	object	—	Lock specific form fields after signing

Where the key is kept

Upload the PKCS#12 file to your workspace's certs folder, then name it by that path (certs/signer.p12):

POST /v1/{tenantId}/assets/certs
Content-Type: multipart/form-data

file: signer.p12

The folder takes .p12 and .pfx files up to 64 KB. A key is listed by name and can be replaced or deleted; it is never served back. A document whose signature cannot be applied is refused (SIGNATURE_NOT_APPLIED) and is neither stored nor counted.

A key kept in your own vault

A signing key can stay in an Azure Key Vault or managed HSM of your own. The platform never holds it: for each signature it sends your vault a digest, and your vault returns the signature. You can take the access back at any time.

In Settings, Signing keys, copy the platform's application (client) ID.
In your Microsoft Entra directory, consent to that application, then give it the Key Vault Crypto User role on the key (or a policy allowing sign and get).
On the key, in your vault, set the tag docpayload-tenant to your workspace's ID, shown in Settings, Signing keys. The application is the same for every customer of the platform, so the tag is how you say which workspace signs with your key: a key without it, or bound to another workspace, is not registered.
Register the key: a name, the key's identifier with its version (https://{vault}.vault.azure.net/keys/{name}/{version}), your directory (tenant) ID, and the certificate chain as PEM, the signer's certificate first.

Registration reads the key's tag, then asks your vault to sign a test digest and checks the signature against the certificate, so a key is only registered once it is bound to your workspace, the platform can use it and the certificate is that key's. A document then names the key where it would name a file, with no password:

{
  "document": {
    "signature": {
      "certificate": "contracts",
      "appearance": { "signedBy": "Contracts" }
    },
    "content": [{ "p": "Signed in our own vault." }]
  }
}

A name is lower-case letters, digits and hyphens, so it is never mistaken for a file's path. An RSA key signs over the digest the document asks for; a P-256, P-384 or P-521 key signs over SHA-256, SHA-384 or SHA-512 respectively. If the vault does not sign when a document is generated, or signs with another key than the certificate's, or the certificate has expired, the document is refused (SIGNATURE_NOT_APPLIED).

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`
`style`	string	Named style of the signature block (see below)
`icon`	string	Icon on the block's top right corner: `lock` or `shield`. None by default
`certificateFingerprint`	boolean	`true` adds a line with the start of the signing certificate's SHA-256 fingerprint
`svg`	object	An svg drawn at the right of the block: a seal placed with `use`, or any drawing (see below)

Styling the block

With no style, the block is drawn in a thin dark frame, in 6pt text, the signer's name in bold. Name a style from styles to change it; the PDF and the DOCX draw the same block.

Style key	What it sets
`fontSize`	Size of the lines
`color`	Colour of the lines
`fontWeight`	`bold` sets every line in bold (the signer's name is always bold)
`border`	The frame: its width and colour, the same on four sides. A style with no border draws no frame
`backgroundColor`	Fill behind the lines; an icon is drawn in this colour
`padding`	Space between the frame and what the block holds: one length for every side, or a side at a time with `paddingTop`, `paddingRight`, `paddingBottom` and `paddingLeft`

{
  "styles": {
    "seal": { "fontSize": 9, "color": "#1D4ED8", "border": "1.5pt solid #1D4ED8", "backgroundColor": "#EFF6FF", "padding": 6 }
  },
  "signature": {
    "certificate": "certs/signer.p12",
    "password": "certPassword",
    "appearance": { "signedBy": "Lisa Thompson", "style": "seal", "icon": "lock", "certificateFingerprint": true }
  }
}

A line wider than the block is clipped and reported; widen position.width or lower fontSize.

A seal or any drawing

svg takes the same svg node a page's content takes, and draws it inside the block, at its right, as tall as the block allows; the lines keep the room to its left. Place a seal component with use, with its own parameters:

{
  "signature": {
    "certificate": "certs/signer.p12",
    "password": "certPassword",
    "position": { "pageNumber": 1, "left": 58, "bottom": 110, "width": 330, "height": 120 },
    "appearance": {
      "signedBy": "Verdania Certification B.V.",
      "reason": "Sealed as issued",
      "svg": {
        "viewBox": [132, 132],
        "children": [
          { "use": { "name": "digital-eseal", "x": 0, "y": 0, "width": 132, "height": 132,
                     "params": { "title": "VERDANIA REGISTRY", "caption": "ELECTRONICALLY SEALED", "docid": "VC-27001-2026-04417" } } }
        ]
      }
    }
  }
}

An appearance with an svg and no lines draws the svg alone. In the PDF the drawing is part of the signature field itself; in the DOCX it is drawn at the same place on the page. Like the icon, it is a drawing and says nothing of whether the signature verifies. A link on one of its shapes is not made, and the report says so: the block is one drawing, the signature's own, and no part of it is a link.

Icon and fingerprint

icon draws a lock or a shield on a small tab in the block's top right corner, in the frame's colour. It is decoration: it looks the same whether or not the signature verifies, and only the reader's signature panel tells you that.

certificateFingerprint adds a last line, Certificate SHA-256: followed by the first eight bytes of the signing certificate's fingerprint. A reader can compare it with the fingerprint the certificate's holder publishes. Like every line in the block it is drawn text, not proof: the signature panel is what verifies the document.

Certification levels

Level	Description
`noChanges`	Default: no modifications allowed after signing
`formFilling`	Only form field filling is allowed
`annotating`	Form filling and annotations are allowed
`unspecified`	No certification: an approval signature

Field lock

The fieldLock object restricts form field modifications after signing.

Property	Type	Description
`permissions`	string	What may still change once the locked fields are signed: `noChanges`, `formFilling` (the default) or `annotating`, the words of `certificationLevel`
`action`	string	`all` (the default) locks every field; `include` locks those in `fields`, `exclude` every field but those
`fields`	string[]	The field names `include` locks or `exclude` leaves unlocked; required by both, refused beside `all`

In a DOCX

A DOCX is signed from the same signature object, with the same key and digest: the whole file is signed as an Office Open XML package signature (XML Signature with XAdES), and timestampServer adds a timestamp to it. A visible signature is drawn in the same box, with the same signer, reason, location and date.

A package signature is broken by any change to the file, so some keys have no equivalent. Each one set is reported, and not applied:

Key	Why
`certificationLevel` other than `noChanges`, `fieldLock`	a package signature allows no later change at all
`signingType: "Detached"`	the package is always signed in place
`contactInfo`, `signatureCreator`, `claimedSignDate`	a package signature has no entry for them
`appearance.image`	the visible signature is drawn as text

fieldName names the PDF's signature field; a package signature has none.

Examples

Basic visible signature

{
  "document": {
    "signature": {
      "fieldName": "approval_sig",
      "certificate": "certs/signer.p12",
      "password": "certPassword",
      "signingType": "PAdES",
      "signatureCreator": "DocPayload",
      "contactInfo": "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": "noChanges"
    },
    "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": "formFilling",
      "fieldLock": {
        "permissions": "formFilling",
        "action": "all"
      },
      "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." }
    ]
  }
}

Properties​

Where the key is kept​

A key kept in your own vault​

Signing types​

Position​

Appearance​

Styling the block​

A seal or any drawing​

Icon and fingerprint​

Certification levels​

Field lock​

In a DOCX​

Examples​

Basic visible signature​

Invisible signature​

Signature with timestamp server​

Signature with field locking​