OneSpan Sign Developer: Optional Signatures and Support for Extraction Methods

Duo Liang,

With the release of OneSpan Sign 11.21, we have added support for the integration of Optional Signatures via document extraction and text tag extraction. As a sender, you can now easily set signatures as optional and no longer need to create and update signatures in a separate step.

In this blog, we will dive into the newly added syntax in document extraction and text tag Features, which are related to the Optional Signature setting, and demonstrate how to use them step by step.

Document Extraction & Optional Signature

The document extraction feature automatically creates all signatures and fields present in an uploaded PDF file. OneSpan Sign retains the positions and sizes of the signatures and fields in the PDF file from the PDF form.

To make a signature field optional, use the following format:


The last “.Optional” part is extended in order to set the signature as optional. Here are a few more examples:

[Agent1.Fullname1]  ====> [Agent1.Fullname1.Optional]  
[Client1.Capture1]  ====> [Client1.Capture1.Optional]
[Client2.Initials1]  ====> [Client2.Initials1.Optional]  


  • 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.

Quick Demo:

We will have a quick demo in this section and bring you with most direct image of how’s the feature is implemented.

First, we put three types of signatures in both required and optional settings in our PDF:12-20-1 

You can download a copy of the PDF above here.

Next, the code to create the package for Java Developers is available in this codeshare. For .NET developers, refer to this codeshare. Moreover, if other users have already enabled Document Extraction for your Account level by contacting our support team, they can log onto the Web UI, create a signer, and then upload the above document.

Once the package is created, all signatures should appear as expected.12-20-2

Text Tags Extraction & Optional Signature

Text Tag Extraction feature automatically extracts signatures and fields by placing Text Tags directly in a document. In other words, OneSpan Sign will analyze the uploaded document and replace every text that matches the Text Tag pattern with the appropriate signature or field.

The following line demonstrates the syntax of a Text Tag:


The third character “X” can be either a question mark (?) or an asterisk (*). An asterisk indicates that an Input Field or Signature is required. A question mark indicates that it is optional. And after 11.21 version, this syntax is also available for all Signature Types.

Some examples below:

{{?esl_Signature1:Signer1:signature}} or {{*esl_Initials1:Signer1:initials}} or {{esl_Initials1:Signer1:initials}}

means an Optional Fullname Signature with name of “Signature1” binding to Signer1.

{{*esl_Initials1:Signer1:initials}} / {{esl_Initials1:Signer1:initials}}
means an Initials Signature with name of “Initials1” binding to Signer1 and this signature is required.


  • For creating signatures, if neither “?” or “*” is set, by default OneSpan Sign will create a required signature, which is the opposite behavior as other fields. Which means it’s not mandatory to add “*” to specify your signatures are required.
  • Unlike Document Extraction, Text Tags syntax is case sensitive including Role Name and Field Type.
  • Refer to this document page for more information on Document Extraction.

Quick Demo:

First, let’s put text tags for all signature types in required and optional ways in our PDF:12-20-3

You can download the sample document above here.

The code to create a package with such a document is provided for Java SDK here and for .Net SDK here. Alternatively, if you have the Text Tag Feature enabled at your account level, you can simply go create a package from your Web UI, create a signer first and upload the above document.

Once you created the package, you should see the signatures as shown in the screenshot below:12-20-4

This completes the updates to the syntax of Document Extraction and Text Tags Extraction. Now, you are prepared to enable Optional Signatures in a real development.

If you have any questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!

Duo Liang is a Technical Evangelist and Partner Integrations Developer at OneSpan where he creates and maintains integration guides and code shares, helps customers and partners integrate OneSpan products into their applications, and builds integrations within third party platforms.