Signatures can be specified as "optional" for all types of signatures. If this flag is set, a signer is not obliged to sign all of their signatures inside a transaction's documents before completing the transaction. Note: At least one signer must have a required signature or a separate "Accept Only" document for a transaction to be completed. (Not including the Default Consent form)

Basic Usage

The "Optional Signature" feature was introduced in version 11.19, so please make sure your SDK version is this version or later. Below is a sample example code on how to build your Signature object and set it as optional.
Signature fullnameOptionalSignature = SignatureBuilder.signatureFor("[email protected]")
	    .onPage(0)
	    .atPosition(100, 100)
	    .makeOptional()
	    .build();
Similarly, makeOptional() function is also available for other signature types:
Signature captureOptionalSignature = SignatureBuilder.captureFor("[email protected]")
	    .onPage(0)
	    .atPosition(100, 200)
	    .makeOptional()
	    .build();
Signature initialsOptionalSignature = SignatureBuilder.initialsFor("[email protected]")
	    .onPage(0)
	    .atPosition(100, 300)
	    .makeOptional()
	    .build();
Signature mobileOptionalSignature = SignatureBuilder.mobileCaptureFor("[email protected]")
	    .onPage(0)
	    .atPosition(100, 400)
	    .makeOptional()
	    .build();

Running Your Code

After running your code, this is what the signer will see in the Signing Ceremony:

Capture

As you see, the Optional Signature stickies will be displayed in a blue color and the boxes are with dotted border and text "(Optional)" appended to the signature text makes them visually different from required signature boxes. After all required signatures are signed, the signer can confirm a document even though not all optional signatures are signed.

Get the Code

With Document Extraction

To make a signature field optional, apply the following format to your PDF form:

[Signer.SigStyle#.Optional]
The last ".Optional" part is extended in order to set the signature as optional. Here are a few more examples:

Capture

You can download the sample PDF here. Note:

  • Signatures are by default required, so only add .Optional when necessary.
  • PDF form name syntax is case insensitive, including Role Name/Custom ID of the signer. [Agent1.Fullname1.Optional] is treated the same as [AGENT1.FULLNAME1.OPTIONAL]
  • This syntax extension is only available for signatures and will not be recognized when creating any other fields. (Names like [Agent1.Fullname1.Textfield1.Optional] will not work)
  • Refer to this document page for more information on Document Extraction
Once the transaction is created, all signatures should appear as expected.

Capture

Get the Code

With Text Tags Extraction

The following line demonstrates the syntax of a Text Tag:
{{Xesl[_fieldName]:roleName:fieldType[:parameter1,parameter2,...]}}
If you put the third character "X" a question mark (?), it indicates that this signature is optional. Otherwise, all signatures are required by default. Some examples below:

Capture

You can download the sample document here. {{?esl:Signer1:Signature}} means an Optional Fullname Signature binding to Signer1. Refer to this document page for more information on Text Tags Extraction. Once you created the transaction, you should see the signatures as shown in the screenshot below, all optional signatures boxes are in dotted line: Capture

Get the Code

Signatures can be specified as "optional" for all types of signatures. If this flag is set, a signer is not obliged to sign all of their signatures inside a transaction's documents before completing the transaction. Note: At least one signer must have a required signature or a separate "Accept Only" document for a transaction to be completed. (Not including the Default Consent form)

Basic Usage

The "Optional Signature" feature was introduced in version 11.19, so please make sure your SDK version is this version or later. Below is a sample example code on how to build your Signature object and set it as optional.
Signature fullnameOptionalSignature = SignatureBuilder.SignatureFor("[email protected]")
	    .OnPage(0)
	    .AtPosition(100, 100)
	    .MakeOptional()
	    .Build();
Similarly, MakeOptional() function is also available for other signature types:
Signature captureOptionalSignature = SignatureBuilder.CaptureFor("[email protected]")
	    .OnPage(0)
	    .AtPosition(100, 200)
	    .MakeOptional()
	    .Build();
Signature initialsOptionalSignature = SignatureBuilder.InitialsFor("[email protected]")
	    .OnPage(0)
	    .AtPosition(100, 300)
	    .MakeOptional()
	    .Build();
Signature mobileOptionalSignature = SignatureBuilder.MobileCaptureFor("[email protected]")
	    .OnPage(0)
	    .AtPosition(100, 400)
	    .MakeOptional()
	    .Build();

Running Your Code

After running your code, this is what the signer will see in the Signing Ceremony:

Capture

As you see, the Optional Signature stickies will be displayed in a blue color and the boxes are with dotted border and text "(Optional)" appended to the signature text makes them visually different from required signature boxes. After all required signatures are signed, the signer can confirm a document even though not all optional signatures are signed.

Get the Code

With Document Extraction

To make a signature field optional, apply the following format to your PDF form:
[Signer.SigStyle#.Optional]
The last ".Optional" part is extended in order to set the signature as optional. Here are a few more examples:

Capture

You can download the sample PDF here. Note:

  • Signatures are by default required, so only add .Optional when necessary.
  • PDF form name syntax is case insensitive, including Role Name/Custom ID of the signer. [Agent1.Fullname1.Optional] is treated the same as [AGENT1.FULLNAME1.OPTIONAL]
  • This syntax extension is only available for signatures and will not be recognized when creating any other fields. (Names like [Agent1.Fullname1.Textfield1.Optional] will not work)
  • Refer to this document page for more information on Document Extraction
Once the transaction is created, all signatures should appear as expected.

Capture

Get the Code

With Text Tags Extraction

The following line demonstrates the syntax of a Text Tag:
{{Xesl[_fieldName]:roleName:fieldType[:parameter1,parameter2,...]}}
If you put the third character "X" a question mark (?), it indicates that this signature is optional. Otherwise, all signatures are required by default. Some examples below:

Capture

You can download the sample document here. {{?esl:Signer1:Signature}} means an Optional Fullname Signature binding to Signer1. Refer to this document page for more information on Text Tags Extraction. Once you created the transaction, you should see the signatures as shown in the screenshot below, all optional signatures boxes are in dotted line:

Capture

Get the Code

Signatures can be specified as "optional" for all types of signatures. If this flag is set, a signer is not obliged to sign all of their signatures inside a transaction's documents before completing the transaction. Note: At least one signer must have a required signature or a separate "Accept Only" document for a transaction to be completed. (Not including the Default Consent form) You can get the complete example code for this guide from the Developer Community Code Share, here.

Basic Usage

The sample request below show you how to add optional signatures to your package. 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="optional signature basic usage.pdf"
Content-Type: application/pdf
%PDF-1.5
%µµµµ
1 0 obj
<>>>
endobj.... 
------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="payload"
{
  "documents": [
    {
      "approvals": [
        {
          "fields": [
            {
              "height": 50,
              "left": 100,
              "page": 0,
              "subtype": "FULLNAME",
              "top": 100,
              "type": "SIGNATURE",
              "width": 200
            }
          ],
          "id":"signature1",
          "role": "Role1"
        },
        {
          "fields": [
            {
              "height": 50,
              "left": 100,
              "page": 0,
              "subtype": "FULLNAME",
              "top": 300,
              "type": "SIGNATURE",
              "width": 200
            }
          ],
          "id":"signature2",
          "role": "Role1",
          "optional": true
        }
      ],
      "name": "Test Document"
    }
  ],
  "name": "Optional Signature Basic Usage REST",
  "roles": [
    {
      "id": "Role1",
      "signers": [
        {
          "email": "[email protected]",
          "firstName": "1.firstname",
          "lastName": "1.lastname",
          "company": "OneSpan Sign"
        }
      ]
    }
  ],
  "type": "PACKAGE",
  "status": "SENT"
}
------WebKitFormBoundary1bNO60n7FqP5WO4t--
For a complete description of each field, take a look at the Request Payload section below.

Response Payload

{
    "id": "7g-LhL0zEzN0jZi7Yccell7y6jA="
}

Running Your Code

After running your code (download link, at bottom), this is what the signer will see in the Signing Ceremony:

Capture

As you see, the Optional Signature stickies will be displayed in a blue color and the boxes are with dotted border and text "(Optional)" appended to the signature text makes them visually different from required signature boxes. After all required signatures are signed, the signer can confirm a document even though not all optional signatures are signed.

With Document Extraction

To make a signature field optional, apply the following format to your PDF form:
[Signer.SigStyle#.Optional]
The last ".Optional" part is extended in order to set the signature as optional. Here are a few more examples:

Capture

You can download the sample PDF here. Note:

  • Signatures are by default required, so only add .Optional when necessary.
  • PDF form name syntax is case insensitive, including Role Name/Custom ID of the signer. [Agent1.Fullname1.Optional] is treated the same as [AGENT1.FULLNAME1.OPTIONAL]
  • This syntax extension is only available for signatures and will not be recognized when creating any other fields. (Names like [Agent1.Fullname1.Textfield1.Optional] will not work)
  • Refer to this document page for more information on Document Extraction

Below example shows you how to use Document Extraction feature automatically create signatures and fields:

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="optional signature with document extraction.pdf"
Content-Type: application/pdf
%PDF-1.5
%µµµµ
1 0 obj
<>>>
endobj.... 
------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="payload"
{
  "documents": [
    {
      "extract": true,
      "name": "Test Document"
    }
  ],
  "name": "Optional Signature with Document Extraction REST",
  "roles": [
    {
      "id": "Role1",
      "signers": [
        {
          "email": "[email protected]",
          "firstName": "1.firstname",
          "lastName": "1.lastname",
          "company": "OneSpan Sign"
        }
      ]
    }
  ],
  "type": "PACKAGE",
  "status": "SENT"
}
------WebKitFormBoundary1bNO60n7FqP5WO4t--
For a complete description of each field, take a look at the Request Payload section below.

Response Payload

{
    "id": "7zZkoGlj0VpeyZA2XcvjWRRePfw="
}
Once the transaction is created, all signatures should appear as expected.

Capture

With Text Tags Extraction

The following line demonstrates the syntax of a Text Tag:
{{Xesl[_fieldName]:roleName:fieldType[:parameter1,parameter2,...]}}
If you put the third character "X" a question mark (?), it indicates that this signature is optional. Otherwise, all signatures are required by default. Some examples below:

Capture

You can download the sample document here. {{?esl:Signer1:Signature}} means an Optional Fullname Signature binding to Signer1. Refer to this document page for more information on Text Tags Extraction. Below example shows you how to use Text Tags feature automatically create signatures and fields:

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="optional signature with text tags extraction.pdf"
Content-Type: application/pdf
%PDF-1.5
%µµµµ
1 0 obj
<>>>
endobj.... 
------WebKitFormBoundary1bNO60n7FqP5WO4t
Content-Disposition: form-data; name="payload"
{
  "documents": [
    {
      "extract": true,
      "extractionTypes":[
         "TEXT_TAGS"
      ],
      "name": "Test Document"
    }
  ],
  "name": "Optional Signature with Text Tags Extraction REST",
  "roles": [
    {
      "id": "Role1",
      "signers": [
        {
          "email": "[email protected]",
          "firstName": "1.firstname",
          "lastName": "1.lastname",
          "company": "OneSpan Sign"
        }
      ]
    }
  ],
  "type": "PACKAGE",
  "status": "SENT"
}
------WebKitFormBoundary1bNO60n7FqP5WO4t--
For a complete description of each field, take a look at the Request Payload section below.

Response Payload

{
    "id": "WAvWnaUQZotN6w_CtDDvn-Wr74s="
}
Once you created the transaction, you should see the signatures as shown in the screenshot below, all optional signatures boxes are in dotted line:

Capture

Get the Code

Request Payload

PropertyTypeEditableRequiredDefaultSample Value(s)
statusstringYesNoDRAFTDRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
typestringYesNoPACKAGEPACKAGE / TEMPLATE / LAYOUT
namestringYesYesn/aText Tags Example Package
documents
idstringYesNon/asample-contract
namestringYesNon/aTest Document
extractbooleanYesNofalsetrue / false
extractionTypesstring arrayYesNo[]["TEXT_TAGS","ACROFIELDS"]
approvals
fields
subtypestringYesNon/aFULLNAME / INITIALS / CAPTURE / MOBILE_CAPTURE / LABEL / TEXTFIELD / TEXTAREA / CHECKBOX / DATE / RADIO / LIST
typestringYesNon/aSIGNATURE / INPUT
extractbooleanYesNofalsetrue / false
heightintegerYesNo5050 / 100 / 150 ...
leftintegerYesNo050 / 100 / 150 ...
pageintegerYesNo00 / 1 / 2 ...
topintegerYesNo050 / 100 / 150 ...
widthintegerYesNo20050 / 100 / 150 ...
rolestringYesNon/aClient1
optionalbooleanYesNofalsetrue / false
roles
idstringYesNon/asigner1
namestringYesNon/asigner1
typestringYesNoSIGNERSIGNER / SENDER
signers
emailstringYesYesn/a[email protected]
firstNamestringYesYesn/aJohn
lastNamestringYesYesn/aSmith
idstringYesNon/asigner1