Enforcing Signature Capture

Signature enforceCaptureSignature = SignatureBuilder.captureFor("[email protected]")
	    .onPage(0)
	    .atPosition(100, 200)
	    .enableEnforceCaptureSignature()
	    .build();

In OneSpan Sign, signers will only be asked to draw their signature once by default. If the transaction requires multiple signatures on the document, OneSpan Sign will automatically replicate the first drawn signature for any subsequent signatures. However, you have the option to require your signer to draw their signature on any given capture signature. This guide will focus on enforcing signature capture at the signature level. If you are looking to enforce this at the transaction level, which would take care of forcing all capture signatures be redrawn, refer to the Signing Ceremony Customization guide.

The Code

"Enforce Signature Capture" feature was introduced in version 11.18. Please make sure your SDK version is later than this. To enable this feature, simply add the .EnableEnforceCaptureSignature() option to your signature builder, as seen below:

Signature enforceCaptureSignature = SignatureBuilder.CaptureFor("[email protected]")
            .WithId(new SignatureId("Signature1"))
            .OnPage(0)
            .AtPosition(100, 200)
            .EnableEnforceCaptureSignature()
	    .Build();

Though applying the feature is simple, there are a couple additional considerations to keep in mind: (1) "enforceCaptureSignature" is set false by default both in the package or signature level setting which means you don’t need to specifically configure it if you don’t use this feature. (2) Unlike the "enforceCaptureSignature": true setting in package level, which requires the signer to capture signature every capture approval, this setting at the signature level only forces the signer to capture his/her signature when the approval contains the "true" setting.

Running Your Code

In the sample code (download link, below), we have three approvals and only the second signature was marked as "enforce capture". This is what you will see after the package was signed:

For the second signature, because we enabled the "enforceCaptureSignature" setting, you’ll see that the signature differs from the first one and it overwrites the cached signature data at the same time. Therefore, the new captured signature automatically replicates when the signer signs the third field.

Get the Code

In OneSpan Sign, signers will only be asked to draw their signature once by default. If the transaction requires multiple signatures on the document, OneSpan Sign will automatically replicate the first drawn signature for any subsequent signatures. However, you have the option to require your signer to draw their signature on any given capture signature. This guide will focus on enforcing signature capture at the signature level. If you are looking to enforce this at the transaction level, which would take care of forcing all capture signatures be redrawn, refer to the Signing Ceremony Customization guide.

The Code

The sample request below show you how to set enforceCaptureSignature : true at approval level. If you need a comparison to the basic document object creation or if this is the first time creating a package with the REST API, see this guide.

HTTP Request

POST /api/packages

HTTP Headers

Accept: application/json Content-Type: application/json Authorization: Basic api_key

Request Payload

------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="file"; filename="enforce capture signature.pdf"
Content-Type: application/pdf
%PDF-1.5
%µµµµ
1 0 obj
<>>>
endobj.... 
------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="payload"
{
  "documents": [
    {
      "approvals": [
        {
          "fields": [
            {
              "height": 50,
              "id": "Signature1",
              "left": 100,
              "page": 0,
              "subtype": "CAPTURE",
              "top": 100,
              "type": "SIGNATURE",
              "width": 200
            }
          ],
          "id": "Signature1",
          "role": "signer1"
        },
        {
          "fields": [
            {
              "height": 50,
              "id": "Signature2",
              "left": 100,
              "page": 0,
              "subtype": "CAPTURE",
              "top": 200,
              "type": "SIGNATURE",
              "width": 200
            }
          ],
          "id": "Signature2",
          "role": "signer1",
          "enforceCaptureSignature": true
        },
        {
          "fields": [
            {
              "height": 50,
              "id": "Signature3",
              "left": 100,
              "page": 0,
              "subtype": "CAPTURE",
              "top": 300,
              "type": "SIGNATURE",
              "width": 200
            }
          ],
          "id": "Signature3",
          "role": "signer1"
        }
      ],
      "name": "Document1",
      "id": "Document1"
    }
  ],
  "name": "test Enforce Capture at Signature Level",
  "roles": [
    {
      "id": "signer1",
      "signers": [
        {
          "email": "[email protected]",
          "firstName": "John",
          "id": "signer1",
          "lastName": "Smith"
        }
      ]
    }
  ],
  "type": "PACKAGE",
  "status": "SENT"
}
------WebKitFormBoundary1bNO60n7FqP5WO4t--

For a complete description of each field, take a look at the Request Payload section below.

Response Payload

{
    "id": "Q6v0Tn_v62G5tfRY43VBE-TEbU4="
}

Though applying the feature is simple, there are a couple additional considerations to keep in mind: (1) "enforceCaptureSignature" is set false by default both in the package or signature level setting which means you don’t need to specifically configure it if you don’t use this feature. (2) Unlike the "enforceCaptureSignature": true setting in package level, which requires the signer to capture signature every capture approval, this setting at the signature level only forces the signer to capture his/her signature when the approval contains the "true" setting.

Running Your Code

In the sample code (download link, below), we have three approvals and only the second signature was marked as "enforce capture". This is what you will see after the package was signed:

For the second signature, because we enabled the "enforceCaptureSignature" setting, you’ll see that the signature differs from the first one and it overwrites the cached signature data at the same time. Therefore, the new captured signature automatically replicates when the signer signs the third field.

Get the Code

Request Payload

Property	Type	Editable	Required	Default	Sample Value(s)
status	string	Yes	No	DRAFT	DRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
type	string	Yes	No	PACKAGE	PACKAGE / TEMPLATE / LAYOUT
name	string	Yes	Yes	n/a	Enforce Capture Signature Example
documents
name	string	Yes	No	n/a	sample doc
approvals
fields
subtype	string	Yes	No	n/a	FULLNAME / INITIALS / CAPTURE / MOBILE_CAPTURE / LABEL / TEXTFIELD / TEXTAREA / CHECKBOX / DATE / RADIO / LIST
type	string	Yes	No	n/a	SIGNATURE / INPUT
extract	boolean	Yes	No	false	true / false
height	integer	Yes	No	50	50 / 100 / 150 ...
left	integer	Yes	No	0	50 / 100 / 150 ...
page	integer	Yes	No	0	0 / 1 / 2 ...
top	integer	Yes	No	0	50 / 100 / 150 ...
width	integer	Yes	No	200	50 / 100 / 150 ...
role	string	Yes	No	n/a	Client1
enforceCaptureSignature	boolean	Yes	No	false	true / false
roles
id	string	Yes	No	n/a	Client1
name	string	Yes	No	n/a	Client1
type	string	Yes	No	SIGNER	SIGNER / SENDER
signers
email	string	Yes	Yes	n/a	[email protected]
firstName	string	Yes	Yes	n/a	John
lastName	string	Yes	Yes	n/a	Smith
phone	string	Yes	No	n/a	514-555-8888
id	string	Yes	No	n/a	Client1
company	string	Yes	No	n/a	Acme Inc.
title	string	Yes	No	n/a	Managing Director