OneSpan Sign developers: Signer attachments management

OneSpan Sign provides a remarkable feature enabling signers to upload attachments during the signing process. This not only empowers signers but also facilitates senders to review the attachment and conclude the transaction. 

In this blog post, we will explore how a sender can mandate a signer to contribute an attachment to the transaction. Without further delay, let's dive right in!

Creating an Attachment Request

First, we will demonstrate three methods in SDK and RESTful API to modify the signer block and request a file attachment in transaction creation.

In Java SDK:

.withSigner(SignerBuilder.newSignerWithEmail("[email protected]")
  .withFirstName("John")
 .withLastName("Doe")
 .withCustomId("Signer1")
 .withAttachmentRequirement(AttachmentRequirementBuilder.newAttachmentRequirementWithName("Driver's license")
	 .withDescription("Please upload a copy of your driver’s license.")
	 .isRequiredAttachment()
	 .build()))

In .NET SDK:

.WithSigner(SignerBuilder.NewSignerWithEmail("[email protected]")
    .WithFirstName("John")
    .WithLastName("Doe")
    .WithCustomId("Signer1")
    .WithAttachmentRequirement(AttachmentRequirementBuilder.NewAttachmentRequirementWithName("Driver's license")
        .WithDescription("Please upload a copy of your driver’s license.")
        .IsRequiredAttachment()
        .Build()))

Via RESTful API:

{
  "id": "Signer1",
  "name": "Signer1",
  "index": 1,
  "attachmentRequirements": [
    {
      "description": "Please upload a scanned copy of your driver's license.",
      "required": true,
      "name": "Driver's license"
    }
  ],
  "signers": [
    {
      "firstName": "John",
      "lastName": "Smith",
      "email": "[email protected]"
    }
  ]
}

You have the freedom to specify a name and a description of the file upload you're requesting. The name and description cannot be longer than 255 characters each. Additionally, you can determine whether the attachment is mandatory. While the description and requirement are optional, the attachment ID is auto-generated by the OSS system and can't be modified. 

Allowlisting Upload Types

With your security being a dominant concern, OneSpan Sign offers a global blocklist, forbidding certain upload types such as "EXE", "DLL", "MSI", "DMG", "SO". Moreover, if you require specific file types, you can establish an allowlist in your account.

For instance, if your integration solely expects an image copy, you can set your allowlist to include “JPG”, “JPEG”, “PNG”, and thus prevent all other types from being uploaded.

The default whitelist includes PDF, DOC, DOCX, RTF, ODT, JPG, JPEG, PNG, BMP, TXT, TIFF, TIF, GIF, XLS, XLSX. Feel free to reach out to our support team for customized adjustments. 

Limiting Files per Attachment

When multiple files are uploaded for a single attachment, these files will be subsequently downloaded as a zip file. If your integration cannot unzip these files, you now have the option to set a maximum number of upload files. If the limit is set to 1, any further upload for the same attachment will activate this error message:

This limitation is a package setting that applies to all associated attachments:

“settings” > “ceremony” > “maxAttachmentFiles” : 1

Ad-hoc users can adjust the value directly in the transaction or template settings panel.

The general size limit for single attachment is 16MB:

Join the OneSpan Developer’s Community

In conclusion, OneSpan Sign provides a robust and secure platform for managing signer attachments, enhancing your digital transaction experience. If you have any questions regarding this blog or anything else concerning the integration of OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!