Signature zones

Place in a PDF the zones a signer must fill in: signature, initials, date, text fields, check boxes, lists. Zones are used with digital signature.

Prerequisites

The digital signature flow: see Digital signature. This page details step 2, placing the zones.

Coordinates

Point	Rule
Unit	The PDF point (1/72 inch). A Letter page is 612 x 792 points.
Origin	The top-left corner of the page; y increases downwards.
Zone position	`x` and `y` are the zone's top-left corner.
Page dimensions	`GetPageDimensions` gives a page's width and height as displayed: a page rotated by 90° has its width and height swapped.
Overflow	Nothing checks that a zone stays within the page: check `x + width` and `y + height` yourself.

Example

SignZoneDetails[] zones;
using (var zoneBuilder = new ZoneBuilder(pdf, isPki: true))   // PDF bytes, or its path
{
    var page = zoneBuilder.GetPageDimensions(1);
    float y = page.Height - 150;   // 150 points from the bottom of the page

    zones = new[]
    {
        zoneBuilder.CreateFieldTextZone(page: 1, fieldName: "name", x: 60, y: y - 40, width: 200, height: 20),
        zoneBuilder.CreateFieldSignZone(page: 1, fieldName: "signature", x: 60, y: y, width: 200, height: 50),
        zoneBuilder.CreateFieldDateSignZone(page: 1, fieldName: "date", x: 300, y: y + 15, width: 100, height: 20),
        zoneBuilder.CreateFieldCheckBoxZone(page: 1, fieldName: "accept", x: 60, y: y + 70, required: true),
    };
}

with ZoneBuilder(pdf_path, is_pki=True) as zone_builder:
    width, height = zone_builder.get_page_dimensions(1)
    y = height - 150  # 150 points from the bottom of the page

    zones = [
        zone_builder.create_field_text_zone(page=1, field_name="name", x=60, y=y - 40, width=200, height=20),
        zone_builder.create_field_sign_zone(page=1, field_name="signature", x=60, y=y, width=200, height=50),
        zone_builder.create_field_date_sign_zone(page=1, field_name="date", x=300, y=y + 15, width=100, height=20),
        zone_builder.create_field_checkbox_zone(page=1, field_name="accept", x=60, y=y + 70, required=True),
    ]

$zoneBuilder = new ZoneBuilder($pdfPath, isPki: true);
try {
    [$width, $height] = $zoneBuilder->getPageDimensions(1);
    $y = $height - 150;   // 150 points from the bottom of the page

    $zones = [
        $zoneBuilder->createFieldTextZone(page: 1, fieldName: 'name', x: 60, y: $y - 40, width: 200, height: 20),
        $zoneBuilder->createFieldSignZone(page: 1, fieldName: 'signature', x: 60, y: $y, width: 200, height: 50),
        $zoneBuilder->createFieldDateSignZone(page: 1, fieldName: 'date', x: 300, y: $y + 15, width: 100, height: 20),
        $zoneBuilder->createFieldCheckBoxZone(page: 1, fieldName: 'accept', x: 60, y: $y + 70, required: true),
    ];
} finally {
    $zoneBuilder->close();
}

Always release the ZoneBuilder after use (using, with, close): it keeps the PDF open.

Create the ZoneBuilder

Item	.NET	Python	PHP
PDF source	Its bytes or its path	Its bytes or its path	Its path, or its bytes with `ZoneBuilder::fromBytes`
PKI mode	`isPki`, true by default	`is_pki`, true by default	`isPki`, true by default
Page count	`PageCount` property	`page_count` property	`getPageCount()` method
Chosen mode	`IsPki` property, read only	`is_pki` attribute	Not exposed

PKI mode only allows three zone types: multi-line text, option list and drop-down list. It changes nothing for the other zones. It is on by default: with digital signature, leave it set to true.

Zone types

Every method takes page (starting at 1), fieldName, x and y. All of them except the check box and the radio button also take the width and height. The font size (fontSize) is in points, 12 by default.

Zone	Method	Own parameters (default)	Key points
Signature	`CreateFieldSignZone`	None	Always required.
Initials	`CreateFieldInitialZone`	None	Always required.
Signing date	`CreateFieldDateSignZone`	`fontSize` (12)	Filled in automatically when signing. Always required.
Text	`CreateFieldTextZone`	`defaultValue` (empty), `fontSize` (12), `required` (true)
Number	`CreateFieldNumberZone`	`defaultValue` (0; required in .NET), `fontSize` (12), `required` (true)
Date	`CreateFieldDateZone`	`fontSize` (12), `required` (true)	Date picker.
Check box	`CreateFieldCheckBoxZone`	`isChecked` (false), `required` (false), `requiredFocus` (false)	Fixed size (10 x 10). A required box is always shown unchecked: `isChecked` is then ignored. With `requiredFocus`, the signer must go through the box before completing the signature; `required` turns it on too.
Radio button	`CreateFieldRadioZone`	`groupId` (required), `isSelected` (false)	Fixed size (10 x 10). The field name is the option's value; buttons in the same group share the same `groupId`. Nothing prevents selecting several buttons of a group: select only one.
Multi-line text	`CreateFieldTextAreaZone`	`defaultValue` (empty), `fontSize` (12), `required` (false)	PKI mode only.
Option list	`CreateFieldOptionListZone`	`options` (required), `selectedValues` (none), `multiSelect` (false), `required` (false)	PKI mode only. Without `multiSelect`, only one value can be preselected. No font size.
Drop-down list	`CreateFieldDropdownZone`	`options` (required), `selectedValue` (none), `fontSize` (12), `required` (false)	PKI mode only.

No SDK checks a zone's size or position, its font size, or that preselected values are in options.

Note

Default value. For text, multi-line text and number, the default value is a pre-filled value that the signer sees and can change; it is not a placeholder. It travels with the zone definition: only put in it what the signer is meant to see.

In .NET, the number field requires a default value (defaultValue). In Python and PHP, it defaults to 0.

Assign zones to signers

Each signer gets their definition: their address and, for the file (identified by its SHA-512 hash), their zones in define mode. See step 3 of the complete example.

Several signers: one definition per signer, each with its own zones.
One file per signer: a definition can target only one file.

Fields already in the PDF

With DetectExistingFields (true by default), certification detects the fields already in the PDF:

Case	Behaviour
A single signer	All detected fields are assigned to them.
Several signers	You must provide `DefineRecipients`, which distributes the detected fields among signers; otherwise certification fails.
Several signers, zones placed with `ZoneBuilder` only	Set `DetectExistingFields` to false.

// Receives the signers (each with an empty list) and the detected fields; returns the distribution.
DefineRecipients = (zonesBySigner, detectedFields) =>
{
    var signers = zonesBySigner.Keys.ToList();
    foreach (var field in detectedFields)
    {
        if (field.FieldName.StartsWith("client_")) zonesBySigner[signers[0]].Add(field);
        else if (field.FieldName.StartsWith("advisor_")) zonesBySigner[signers[1]].Add(field);
        else throw new InvalidOperationException("Field outside the naming convention in the PDF");   // never assign by default
    }
    return zonesBySigner;
}

The delegate receives an {address: []} dictionary and the list of detected fields, as raw dictionaries (keys "Type", "Page", "DefaultValue"...): the field name is in DefaultValue. It returns the filled dictionary.

import json

# Receives the signers (each with an empty list) and the detected fields; returns the distribution.
def split_fields(zones_by_signer, detected_fields):
    signers = list(zones_by_signer)
    for field in detected_fields:
        name = json.loads(field.get("DefaultValue") or "{}").get("existingFieldInfos", {}).get("fieldName", "")
        if name.startswith("client_"):
            zones_by_signer[signers[0]].append(field)
        elif name.startswith("advisor_"):
            zones_by_signer[signers[1]].append(field)
        else:
            raise ValueError("Field outside the naming convention in the PDF")  # never assign by default
    return zones_by_signer

# CertifyPdfArgs(..., define_recipients=split_fields)

The delegate receives an [address => []] array and the detected fields (ZoneDetails); it must return the filled array, since PHP arrays are passed by value. The field name is in fieldName.

// Receives the signers (each with an empty list) and the detected fields; returns the distribution.
$splitFields = static function (array $zonesBySigner, array $detectedFields): array {
    $signers = array_keys($zonesBySigner);
    foreach ($detectedFields as $field) {   // ZoneDetails
        if (str_starts_with($field->fieldName, 'client_')) {
            $zonesBySigner[$signers[0]][] = $field;
        } elseif (str_starts_with($field->fieldName, 'advisor_')) {
            $zonesBySigner[$signers[1]][] = $field;
        } else {
            throw new RuntimeException('Field outside the naming convention in the PDF');   // never assign by default
        }
    }
    return $zonesBySigner;
};

// new CertifyPdfArgs(..., defineRecipients: $splitFields)

Detected fields that you assign to no signer are made read-only before certification: nobody can fill them, and they keep the content of the original PDF.

Common errors

Symptom	Likely cause	Solution
"Page out of range" error	Page number below 1 or above the page count	Pages start at 1.
Error when creating a multi-line text, an option list or a drop-down list	`ZoneBuilder` created without PKI mode	Create it in PKI mode.
Certification fails with several signers	Detected fields without `DefineRecipients`	Provide `DefineRecipients`, or set `DetectExistingFields` to false.
"File does not contain existing fields"	`DefineRecipients` provided for a PDF without fields	Set `DetectExistingFields` to false.
A zone appears in the wrong place	Origin taken at the bottom of the page	The origin is the top-left corner; see Coordinates.

Digital signature
Logs: track the signature

Table of Contents