Digital signature

Get a PDF signed with a digital signature: the SDK certifies the PDF with a certificate, then sends it to the signer. It is the recommended signature mode.

Prerequisites

The signature module for your language: SecureExchanges.Signature.NetCore on .NET 8 (SecureExchanges.Signature on .NET Framework), secure-exchanges-sdk[signature] in Python; it is included in the PHP package. See Choose your package.
A Chromium browser on the machine that certifies: the SDK drives it headless.
- .NET: see Docker and Linux for a Linux server or a container.
- Python: playwright install chromium, once per machine (about 150 MB).
- PHP: Chrome or Chromium installed; outside the usual locations, give its path in SE_CHROME_PATH.
Your credentials loaded: see Credentials and environments.

The six steps

Read the PDF and compute its SHA-512 hash. It identifies the file in the next steps.
Place the zones to sign with ZoneBuilder: signature, date, initials, fields. See Signature zones.
Assign the zones to the signer, for this file.
Get the document's certification token with GetCertificationToken.
Certify the PDF with CertifyPkiPdf from PkiFileHelper.
Send the certified PDF with MultiRecipientMessage, passing it in CertifiedPdfs.

Complete example

using System;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;
using SecureExchangesSDK.Helpers;
using SecureExchangesSDK.Models;
using SecureExchangesSDK.Models.Args;
using SecureExchangesSDK.Models.Entity;
using SecureExchangesSDK.Models.JSON;
using SecureExchangesSDK.Models.Transport;
using SecureExchangesSDK.SecureExchanges;
using SecureExchangesSignatureSDK.Helpers;
using SecureExchangesSignatureSDK.Models.Args;

internal static class PkiCertification
{
    private static async Task SendForSignature(string pdfPath, string signer)
    {
        // Your credentials come from your secret store, never from code.
        Guid serial = ReadSecret("SecureExchanges:Serial");
        Guid apiUser = ReadSecret("SecureExchanges:ApiUser");
        Guid apiPassword = ReadSecret("SecureExchanges:ApiPassword");
        var endpoint = new Uri("https://www.secure-exchanges.com/_api/0217/0217.asmx");

        // 1. Read the PDF and compute its SHA-512 hash: it identifies the file in the next steps.
        byte[] pdf = File.ReadAllBytes(pdfPath);
        string sha512 = CryptoHelper.GetSHA512HashOfBytes(pdf);

        // 2. Place the zones to sign (see "Signature zones").
        SignZoneDetails[] zones;
        using (var zoneBuilder = new ZoneBuilder(pdf, isPki: true))
        {
            zones = new[]
            {
                zoneBuilder.CreateFieldSignZone(page: 1, fieldName: "signature1", x: 60, y: 400, width: 200, height: 50),
                zoneBuilder.CreateFieldDateSignZone(page: 1, fieldName: "date1", x: 60, y: 500, width: 100, height: 25),
            };
        }

        // 3. Assign the zones to the signer.
        var zonesBySigner = new List<RecipientZoneDefinition>
        {
            new RecipientZoneDefinition
            {
                Email = signer,
                ZonesDefByFile = new[]
                {
                    new FileZoneDefinition
                    {
                        UniqueName = sha512,
                        IsPKIFile = true,
                        ZonesDef = new SignZoneDefinition { Mode = "define", Zones = zones }
                    }
                }
            }
        };

        // 4. Get the document's certification token.
        var token = SignHelper.GetCertificationToken(new GetCertificationTokenSDKArgs(
            endpoint, serial, apiUser, apiPassword, sha512, CertificationTokenType.CertifyDocument, "en-CA"));
        if (token.Status != 200)
            throw new InvalidOperationException($"Certification token refused, status {token.Status}");

        // 5. Certify the PDF. PkiFileHelper drives a headless browser: release it after use.
        CertifiedPdfContainer certifiedPdf;
        await using (var pki = new PkiFileHelper(isPreview: false, culture: "en-CA"))
        {
            certifiedPdf = await pki.CertifyPkiPdf(new CertifyPdfArgs
            {
                File = new FileArgs(pdf, Path.GetFileName(pdfPath), "application/pdf"),
                Recipients = new List<string> { signer },
                CertifyData = token.CertificationData,
                RecipientZoneDefinitions = zonesBySigner
            });
        }

        // 6. Send the certified PDF to the signer.
        var args = new MutliRecipientArgs(
            endPointUri: endpoint, serial: serial, user: apiUser, psw: apiPassword,
            recipients: new List<RecipientInfo> { new RecipientInfo { Email = signer } },
            message: "Please sign the attached document.",
            subject: "Document to sign",
            password: null, filesList: null,
            sendMode: SendMethodEnum.onlyEmail, getBackHtml: false,
            showSubject: true, getNotify: true, cultureID: "en-CA",
            maximumOpenTime: 5, minutesExpiration: 10080);
        args.CertifiedPdfs = new List<CertifiedPdfContainer> { certifiedPdf };
        args.OwnerDontNeedToSign = true;   // otherwise you sign too, last: false by default in .NET

        var response = MessageHelper.MultiRecipientMessage(args);
        if (response.Status != 200)
            throw new InvalidOperationException($"Sending refused, status {response.Status}");
    }

    private static Guid ReadSecret(string name)
    {
        // Replace with a read from your secret manager (Azure Key Vault, etc.).
        throw new NotImplementedException(name);
    }
}

"""PKI certification: certify a PDF, then send it for signature."""

import asyncio
import os
import uuid

from secure_exchanges_sdk.client import SecureExchangesClient, SEMSClient
from secure_exchanges_sdk.helpers.crypto_helper import CryptoHelper
from secure_exchanges_sdk.helpers.message_helper import MessageHelper
from secure_exchanges_sdk.helpers.pki_file_helper import CertifyPdfArgs, PkiFileHelper
from secure_exchanges_sdk.helpers.settings_helper import SettingsHelper
from secure_exchanges_sdk.helpers.sign_helper import SignHelper
from secure_exchanges_sdk.helpers.zone_builder import ZoneBuilder
from secure_exchanges_sdk.models.entity.recipient_info import RecipientInfo
from secure_exchanges_sdk.models.entity.sign_zone_definition import SignZoneDefinition
from secure_exchanges_sdk.models.transport.file_zone_definition import FileZoneDefinition
from secure_exchanges_sdk.models.transport.recipient_zone_definition import RecipientZoneDefinition


def read_secret(name: str) -> uuid.UUID:
    """Replace with a read from your secret manager (Azure Key Vault, etc.)."""
    raise NotImplementedError(name)


async def send_for_signature(pdf_path: str, signer: str) -> None:
    cfg = SettingsHelper.configure_preview()  # configure_production() in production
    client = SecureExchangesClient(cfg["api_endpoint"])
    sems_client = SEMSClient(cfg["sems_endpoint"])
    serial = read_secret("SecureExchanges:Serial")
    api_user = read_secret("SecureExchanges:ApiUser")
    api_password = read_secret("SecureExchanges:ApiPassword")

    # 1. Read the PDF and compute its SHA-512 hash: it identifies the file in the next steps.
    with open(pdf_path, "rb") as f:
        pdf = f.read()
    sha512 = CryptoHelper.get_sha512_hash_of_bytes(pdf)

    # 2. Place the zones to sign (see "Signature zones").
    with ZoneBuilder(pdf_path, is_pki=True) as zone_builder:
        zones = [
            zone_builder.create_field_sign_zone(page=1, field_name="signature1", x=60, y=400, width=200, height=50),
            zone_builder.create_field_date_sign_zone(page=1, field_name="date1", x=60, y=500, width=100, height=25),
        ]

    # 3. Assign the zones to the signer.
    zones_by_signer = [
        RecipientZoneDefinition(
            email=signer,
            zones_def_by_file=[
                FileZoneDefinition(
                    unique_name=sha512,
                    is_pki_file=True,
                    zones_def=SignZoneDefinition(mode="define", zones=zones),
                )
            ],
        )
    ]

    # 4. Get the document's certification token.
    token = SignHelper.get_certification_token(
        api_client=client, serial=serial, api_user=api_user, api_password=api_password,
        original_hash=sha512, culture_id="en-CA", token_type="CertifyDocument",
    )
    if token["status"] != 200:
        raise RuntimeError(f"Certification token refused, status {token['status']}")

    # 5. Certify the PDF. PkiFileHelper drives a headless browser: release it after use.
    # Same environment as configure_preview(): is_preview=False in production
    async with PkiFileHelper(is_preview=True, culture="en-CA") as pki:
        certified_pdf = await pki.certify_pki_pdf(CertifyPdfArgs(
            file_bytes=pdf,
            file_name=os.path.basename(pdf_path),
            recipients=[signer],
            certify_data=token["certification_data"],
            recipient_zone_definitions=zones_by_signer,
        ))

    # 6. Send the certified PDF to the signer.
    answer = MessageHelper.multi_recipient_message(
        api_client=client, sems_client=sems_client,
        serial=serial, api_user=api_user, api_password=api_password,
        recipients=[RecipientInfo(email=signer)],
        message="<p>Please sign the attached document.</p>",
        subject="Document to sign",
        certified_pdfs=[certified_pdf],
        owner_dont_need_to_sign=True,  # the licence owner does not have to sign
        get_back_html=False, culture_id="en-CA",
    )
    if answer.status != 200:
        raise RuntimeError(f"Sending refused, status {answer.status}")


if __name__ == "__main__":
    asyncio.run(send_for_signature("contract.pdf", "signer@example.com"))

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use SecureExchanges\SDK\Client\SecureExchangesClient;
use SecureExchanges\SDK\Client\SEMSClient;
use SecureExchanges\SDK\Helpers\CryptoHelper;
use SecureExchanges\SDK\Helpers\MessageHelper;
use SecureExchanges\SDK\Helpers\PkiFileHelper;
use SecureExchanges\SDK\Helpers\SettingsHelper;
use SecureExchanges\SDK\Helpers\SignHelper;
use SecureExchanges\SDK\Helpers\ZoneBuilder;
use SecureExchanges\SDK\Models\Args\CertifyPdfArgs;
use SecureExchanges\SDK\Models\Args\FileArgs;
use SecureExchanges\SDK\Models\Entity\RecipientInfo;
use SecureExchanges\SDK\Models\Entity\SignZoneDefinition;
use SecureExchanges\SDK\Models\Transport\FileZoneDefinition;
use SecureExchanges\SDK\Models\Transport\RecipientZoneDefinition;

/** Replace with a read from your secret manager (Azure Key Vault, etc.). */
function readSecret(string $name): string
{
    throw new RuntimeException($name);
}

function sendForSignature(string $pdfPath, string $signer): void
{
    $endpoints = SettingsHelper::configurePreview();   // configureProduction() in production
    $client = new SecureExchangesClient($endpoints['apiEndpoint']);
    $sems = new SEMSClient($endpoints['semsEndpoint']);
    $serial = readSecret('SecureExchanges:Serial');
    $apiUser = readSecret('SecureExchanges:ApiUser');
    $apiPassword = readSecret('SecureExchanges:ApiPassword');

    // 1. Read the PDF and compute its SHA-512 hash: it identifies the file in the next steps.
    $pdf = file_get_contents($pdfPath);
    $sha512 = CryptoHelper::getSha512HashOfBytes($pdf);

    // 2. Place the zones to sign (see "Signature zones").
    $zoneBuilder = new ZoneBuilder($pdfPath, isPki: true);
    try {
        $zones = [
            $zoneBuilder->createFieldSignZone(page: 1, fieldName: 'signature1', x: 60, y: 400, width: 200, height: 50),
            $zoneBuilder->createFieldDateSignZone(page: 1, fieldName: 'date1', x: 60, y: 500, width: 100, height: 25),
        ];
    } finally {
        $zoneBuilder->close();
    }

    // 3. Assign the zones to the signer.
    $zonesBySigner = [
        new RecipientZoneDefinition(
            email: $signer,
            zonesDefByFile: [
                new FileZoneDefinition(
                    uniqueName: $sha512,
                    zonesDef: new SignZoneDefinition(zones: $zones, mode: 'define'),
                    isPKIFile: true,
                ),
            ],
        ),
    ];

    // 4. Get the document's certification token.
    $token = SignHelper::getCertificationToken(
        apiClient: $client, serial: $serial, apiUser: $apiUser, apiPassword: $apiPassword,
        originalHash: $sha512, cultureId: 'en-CA', tokenType: 'CertifyDocument',
    );
    if ($token['status'] !== 200) {
        throw new RuntimeException('Certification token refused, status ' . $token['status']);
    }

    // 5. Certify the PDF. PkiFileHelper drives a headless browser: release it after use.
    // Same environment as configurePreview(): isPreview: false in production
    $pki = new PkiFileHelper(isPreview: true, culture: 'en-CA');
    try {
        $certifiedPdf = $pki->certifyPkiPdf(new CertifyPdfArgs(
            file: new FileArgs($pdf, basename($pdfPath), 'application/pdf'),
            recipients: [$signer],
            certifyData: $token['certification_data'],
            recipientZoneDefinitions: $zonesBySigner,
        ));
    } finally {
        $pki->close();
    }

    // 6. Send the certified PDF to the signer.
    $answer = MessageHelper::multiRecipientMessage(
        apiClient: $client,
        serial: $serial,
        apiUser: $apiUser,
        apiPassword: $apiPassword,
        recipients: [new RecipientInfo(email: $signer)],
        message: 'Please sign the attached document.',
        subject: 'Document to sign',
        getBackHtml: false,
        cultureId: 'en-CA',
        semsClient: $sems,
        certifiedPdfs: [$certifiedPdf],
        ownerDontNeedToSign: true,   // the licence owner does not have to sign
    );
    if ($answer->status !== 200) {
        throw new RuntimeException('Sending refused, status ' . $answer->status);
    }
}

sendForSignature('contract.pdf', 'signer@example.com');

Note

On .NET Framework (SecureExchanges.Signature package), release PkiFileHelper with using rather than await using.

Good to know

Point	Detail
The same PDF at every step	The SHA-512 hash identifies the file: do not modify it between computing the hash and certifying.
Preview	Set `isPreview` to true in your test configuration, with your preview credentials. It must follow the same environment as your other calls: true with the preview configuration, false in production.
Fields already in the PDF	With `DetectExistingFields` (true by default), they are detected; `DefineRecipients` lets you distribute them among signers.
Resources	`PkiFileHelper` starts a browser: release it as soon as certification is done, as in the example.
Several signers	Add one zone definition per signer, and every signer to the recipient list, in signing order: see Several signers.
Options without PKI	`DoNotEncryptPDF` and `DoNotAppendCertificateToFile` are deprecated and need not be used. See Move to digital signature.

Several signers

Signatures happen one after the other, in the order of the recipient list:

The first signer receives the email as soon as the message is sent.
Each following signer receives it once the previous one has signed.
When everything is signed, the signers and the licence owner receive the signed documents.

There is no parallel sending: the order of the list is the signing order. To notify people who do not sign, see Copy recipients.

The licence owner

The owner of the licence that sends the message is always added last to the signing chain. OwnerDontNeedToSign decides whether they must sign:

Value	Effect
true	They do not have to sign: they only receive the signed documents at the end.
false	They sign last, after everyone else. They then need their own zones, otherwise the send is refused.

Warning

The default value is not the same everywhere: false in .NET, true in Python and PHP. Always set it explicitly, as in the example.

Signing options

SignatureOptions, of type SignOptions, sets three aspects of the signing chain: the signing modes offered, a file the signer must attach, and copy recipients who do not sign. It only applies to a send with documents to sign. The example takes up step 6 of the complete example:

using System;
using System.Collections.Generic;
using SecureExchangesSDK.Helpers;
using SecureExchangesSDK.Models;
using SecureExchangesSDK.Models.Args;
using SecureExchangesSDK.Models.Entity;
using SecureExchangesSDK.Models.Enum;
using SecureExchangesSDK.Models.JSON;
using SecureExchangesSDK.Models.Transport;
using SecureExchangesSDK.SecureExchanges;

internal static class SigningOptions
{
    // Step 6 of the complete example, with the signing options: certifiedPdf comes from step 5.
    private static void SendWithOptions(CertifiedPdfContainer certifiedPdf, string signer,
        string copyTo, string blindCopyTo)
    {
        // Your credentials come from your secret store, never from code.
        Guid serial = ReadSecret("SecureExchanges:Serial");
        Guid apiUser = ReadSecret("SecureExchanges:ApiUser");
        Guid apiPassword = ReadSecret("SecureExchanges:ApiPassword");
        var endpoint = new Uri("https://www.secure-exchanges.com/_api/0217/0217.asmx");

        var options = new SignOptions
        {
            // Mode allowed for the signature and the initials: here, drawing only.
            SignatureRestriction = SignatureModeRestriction.Trace,
            // The signer must attach a file to finish: a single signer in this case.
            UploadFileOptions = new SignOptionsFileUpload
            {
                UploadMode = ReplyFileUploadMode.UploadMandatory,
                AuthorizedExtensions = new[] { ".pdf", ".jpg", ".png" },
                Messages = new List<ReplyOptionsMessage>
                {
                    new ReplyOptionsMessage { CultureID = "en-CA", Message = "Attach the completed Schedule B." },
                    new ReplyOptionsMessage { CultureID = "fr-CA", Message = "Joignez l'annexe B remplie." }
                },
                NoEditor = true
            },
            // Notified when the message is sent, they receive the signed documents at the end, without signing.
            CCRecipients = new List<Recipient> { new Recipient { Email = copyTo } },
            // Like the previous ones, but hidden from the signers.
            BCCRecipients = new List<Recipient> { new Recipient { Email = blindCopyTo } }
        };

        var args = new MutliRecipientArgs(
            endPointUri: endpoint, serial: serial, user: apiUser, psw: apiPassword,
            recipients: new List<RecipientInfo> { new RecipientInfo { Email = signer } },
            message: "Please sign the attached document, then attach the completed Schedule B.",
            subject: "Document to sign",
            password: null, filesList: null,
            sendMode: SendMethodEnum.onlyEmail, getBackHtml: false,
            showSubject: true, getNotify: true, cultureID: "en-CA",
            maximumOpenTime: 5, minutesExpiration: 10080);
        args.CertifiedPdfs = new List<CertifiedPdfContainer> { certifiedPdf };
        args.SignatureOptions = options;
        args.OwnerDontNeedToSign = true;   // otherwise you sign too, last: false by default in .NET

        var response = MessageHelper.MultiRecipientMessage(args);
        if (response.Status != 200)
            throw new InvalidOperationException($"Sending refused, status {response.Status}");
    }

    private static Guid ReadSecret(string name)
    {
        // Replace with a read from your secret manager (Azure Key Vault, etc.).
        throw new NotImplementedException(name);
    }
}

"""Signing options: allowed mode, file to attach and copy recipients."""

import uuid

from secure_exchanges_sdk.client import SecureExchangesClient, SEMSClient
from secure_exchanges_sdk.helpers.message_helper import MessageHelper
from secure_exchanges_sdk.helpers.pki_file_helper import CertifiedPdfContainer
from secure_exchanges_sdk.helpers.settings_helper import SettingsHelper
from secure_exchanges_sdk.models.entity.recipient_info import RecipientInfo
from secure_exchanges_sdk.models.entity.tracking_recipient import Recipient
from secure_exchanges_sdk.models.enum.reply_file_upload_mode import ReplyFileUploadMode
from secure_exchanges_sdk.models.json_models.sign_options import SignatureModeRestriction, SignOptions
from secure_exchanges_sdk.models.json_models.sign_options_file_upload import SignOptionsFileUpload
from secure_exchanges_sdk.models.transport.reply_options_message import ReplyOptionsMessage


def read_secret(name: str) -> uuid.UUID:
    """Replace with a read from your secret manager (Azure Key Vault, etc.)."""
    raise NotImplementedError(name)


def send_with_options(certified_pdf: CertifiedPdfContainer, signer: str,
                      copy_to: str, blind_copy_to: str) -> None:
    """Step 6 of the complete example, with the signing options: certified_pdf comes from step 5."""
    cfg = SettingsHelper.configure_preview()  # configure_production() in production
    client = SecureExchangesClient(cfg["api_endpoint"])
    sems_client = SEMSClient(cfg["sems_endpoint"])
    serial = read_secret("SecureExchanges:Serial")
    api_user = read_secret("SecureExchanges:ApiUser")
    api_password = read_secret("SecureExchanges:ApiPassword")

    options = SignOptions(
        # Mode allowed for the signature and the initials: here, drawing only.
        signature_restriction=SignatureModeRestriction.TRACE,
        # The signer must attach a file to finish: a single signer in this case.
        upload_file_options=SignOptionsFileUpload(
            upload_mode=ReplyFileUploadMode.UPLOAD_MANDATORY,
            authorized_extensions=[".pdf", ".jpg", ".png"],
            messages=[
                ReplyOptionsMessage(culture_id="en-CA", message="Attach the completed Schedule B."),
                ReplyOptionsMessage(culture_id="fr-CA", message="Joignez l'annexe B remplie."),
            ],
            no_editor=True,
        ),
        # Notified when the message is sent, they receive the signed documents at the end, without signing.
        cc_recipients=[Recipient(email=copy_to)],
        # Like the previous ones, but hidden from the signers.
        bcc_recipients=[Recipient(email=blind_copy_to)],
    )

    answer = MessageHelper.multi_recipient_message(
        api_client=client, sems_client=sems_client,
        serial=serial, api_user=api_user, api_password=api_password,
        recipients=[RecipientInfo(email=signer)],
        message="<p>Please sign the attached document, then attach the completed Schedule B.</p>",
        subject="Document to sign",
        certified_pdfs=[certified_pdf],
        sign_options=options,
        owner_dont_need_to_sign=True,  # the licence owner does not have to sign
        get_back_html=False, culture_id="en-CA",
    )
    if answer.status != 200:
        raise RuntimeError(f"Sending refused, status {answer.status}")

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use SecureExchanges\SDK\Client\SecureExchangesClient;
use SecureExchanges\SDK\Client\SEMSClient;
use SecureExchanges\SDK\Helpers\MessageHelper;
use SecureExchanges\SDK\Helpers\SettingsHelper;
use SecureExchanges\SDK\Models\Entity\RecipientInfo;
use SecureExchanges\SDK\Models\Enum\ReplyFileUploadMode;
use SecureExchanges\SDK\Models\Enum\SignatureModeRestriction;
use SecureExchanges\SDK\Models\JsonModels\SignOptions;
use SecureExchanges\SDK\Models\JsonModels\SignOptionsFileUpload;
use SecureExchanges\SDK\Models\Transport\CertifiedPdfContainer;
use SecureExchanges\SDK\Models\Transport\ReplyOptionsMessage;

/** Replace with a read from your secret manager (Azure Key Vault, etc.). */
function readSecret(string $name): string
{
    throw new RuntimeException($name);
}

/** Step 6 of the complete example, with the signing options: $certifiedPdf comes from step 5. */
function sendWithOptions(
    CertifiedPdfContainer $certifiedPdf,
    string $signer,
    string $copyTo,
    string $blindCopyTo,
): void {
    $endpoints = SettingsHelper::configurePreview();   // configureProduction() in production
    $client = new SecureExchangesClient($endpoints['apiEndpoint']);
    $sems = new SEMSClient($endpoints['semsEndpoint']);
    $serial = readSecret('SecureExchanges:Serial');
    $apiUser = readSecret('SecureExchanges:ApiUser');
    $apiPassword = readSecret('SecureExchanges:ApiPassword');

    // The signer must attach a file to finish: a single signer in this case.
    $upload = new SignOptionsFileUpload();
    $upload->uploadMode = ReplyFileUploadMode::UPLOAD_MANDATORY;
    $upload->authorizedExtensions = ['.pdf', '.jpg', '.png'];
    $upload->messages = [
        new ReplyOptionsMessage(cultureId: 'en-CA', message: 'Attach the completed Schedule B.'),
        new ReplyOptionsMessage(cultureId: 'fr-CA', message: "Joignez l'annexe B remplie."),
    ];
    $upload->noEditor = true;

    $options = new SignOptions();
    // Mode allowed for the signature and the initials: here, drawing only.
    $options->signatureRestriction = SignatureModeRestriction::TRACE;
    $options->uploadFileOptions = $upload;
    // Notified when the message is sent, they receive the signed documents at the end, without signing.
    $options->ccRecipients = [new RecipientInfo(email: $copyTo)];
    // Like the previous ones, but hidden from the signers.
    $options->bccRecipients = [new RecipientInfo(email: $blindCopyTo)];

    $answer = MessageHelper::multiRecipientMessage(
        apiClient: $client,
        serial: $serial,
        apiUser: $apiUser,
        apiPassword: $apiPassword,
        recipients: [new RecipientInfo(email: $signer)],
        message: 'Please sign the attached document, then attach the completed Schedule B.',
        subject: 'Document to sign',
        getBackHtml: false,
        cultureId: 'en-CA',
        semsClient: $sems,
        certifiedPdfs: [$certifiedPdf],
        signOptions: $options,
        ownerDontNeedToSign: true,   // the licence owner does not have to sign
    );
    if ($answer->status !== 200) {
        throw new RuntimeException('Sending refused, status ' . $answer->status);
    }
}

Allowed signing modes

SignatureRestriction sets the modes the signer may use for their signature and initials. The seal, always an image, is not affected. The restriction applies to every signer in the chain.

Value	Mode offered
`NoRestriction`	All modes. This is the default value.
`Text`	Type their name: it is rendered in cursive writing.
`Trace`	Draw their signature with the mouse or a finger.
`Picture`	Upload an image of their signature, PNG or JPEG, 500 KB at most.

Values combine with the | operator: Text and Trace together offer typing and drawing.

In PHP, combine their ->value with the | operator: SignatureModeRestriction::TEXT->value | SignatureModeRestriction::TRACE->value offers typing and drawing. A value that matches no mode is refused before sending.

File to attach

UploadFileOptions takes a SignOptionsFileUpload, which asks the signer to attach files to their signed documents.

Property	Role
`UploadMode`	`NoUpload`, the default value: no file can be attached. `UploadOptional`: the signer may attach files. `UploadMandatory`: they cannot finish without attaching at least one.
`AuthorizedExtensions`	Allowed extensions, with the dot, for example `.pdf`. A file with another extension is refused; the signed documents are not affected. Without a list, any extension is allowed.
`Messages`	The instruction shown to the signer: one `ReplyOptionsMessage` per culture. Only the instruction whose culture is exactly the page's, `fr-CA` or `en-CA`, is shown: provide both. Write plain text.
`NoEditor`	true: the signer cannot write a message, they only attach files.
`NoReply`	No effect when signing.

Messages also accepts dictionaries in Python, and arrays in PHP, with the CultureID and Message keys.

Important

UploadOptional and UploadMandatory require a single signer. With several recipients, the send is refused.

Copy recipients

CCRecipients and BCCRecipients add recipients who do not sign:

As soon as the message is sent, they are notified that documents are to be signed. They cannot sign them.
When everything is signed, they receive the signed documents.

Those in BCCRecipients are hidden: the signers do not see them, and the final email does not name them.

Each copy recipient has an email address, a phone number, or both. With a number only, they are reached by SMS; with both, they receive the email and a code by SMS.

In .NET, they are Recipient objects from the SecureExchangesSDK.SecureExchanges namespace: only Email and Phone matter.

In Python, they are Recipient objects, exported by secure_exchanges_sdk.models.entity.

In PHP, they are RecipientInfo objects, as for signers.

Common errors

Symptom	Likely cause	Solution
The browser fails to start	Chromium missing or system dependencies missing	See Docker and Linux.
Send refused: "Not all recipients have fields defined for all files"	`OwnerDontNeedToSign` set to false, the .NET default, with no zones for the owner	Set it to true, or add their zones.
Send refused, message starting with "The signature file upload mode"	`UploadOptional` or `UploadMandatory` with several signers	Keep a single signer, or set `UploadMode` to `NoUpload`.
Certification token refused	Credentials, environment or licence	See Status codes and Licence and quotas.
Zones do not appear	Zones assigned to another file or another address	Check the SHA-512 hash and the signer's address.

Signature zones
Logs: track opening and signature
Azure Functions

Table of Contents