Attachment Requirements

This guide will show you how to request, download, and accept/refuse file attachments with OneSpan Sign.

With OneSpan Sign, you have the ability to request attachments after your signer(s) signed your document(s). After the requested attachments have been provided, you will have the option of accepting or rejecting the attachment. In the event of a refusal, you will be able to provide feedback in the form of a short message and the signer will have the opportunity to upload a different file.

The Code

Below is a sample code on how you would edit your signer block to request a file attachment. The withDescription() method allows you to provide a description to the signer about the file upload you’re looking for and the isRequiredAttachment() method defines that you are requiring the attachment. Neither of these are mandatory when building your AttachmentRequirement object. If you need a comparison to the basic document object creation or if this is the first time creating a package (transaction in the new UI) with the Java SDK, see this guide.

.withSigner(newSignerWithEmail("john.doe@gmail.com")
.withFirstName("John")
	.withLastName("Doe")
	.withCustomId("Signer1")
	.withAttachmentRequirement(newAttachmentRequirementWithName("Driver's license")
		.withDescription("Please upload a copy of your driver’s license.")
		.isRequiredAttachment()
		.build()))

Accordingly, you may also want to query the status of each attachment in your package. OneSpan Sign will return AttachmentRequirement objects as a list. The code below will loop through each AttachmentRequirement object and print out the name, status, and id of each requested attachment for that particular signer.

DocumentPackage myPackage = client.getPackage(packageId);
		
List<AttachmentRequirement> signer1Attachments = myPackage.getSigner("john.doe@gmail.com").getAttachmentRequirements();
		
for(AttachmentRequirement attachment : signer1Attachments){
      System.out.println(attachment.getName() + " " + attachment.getStatus() + " " + attachment.getId());
}

Furthermore, you have the option of downloading attachments in three different manners:

  • A single attachment (requires the attachment id)
  • All attachments in a package
  • All attachments from a particular signer
//Download individual attachment
DownloadedFile downloadedAttachment = client.getAttachmentRequirementService().downloadAttachmentFile(packageId, attachmentId);
Files.saveTo(downloadedAttachment.getContents(), downloadedAttachment.getFilename());

//Download all attachments in package	    
DownloadedFile downloadedAllAttachmentsForPackage = client.getAttachmentRequirementService().downloadAllAttachmentFilesForPackage(packageId);
Files.saveTo(downloadedAllAttachmentsForPackage.getContents(), "downloadedAllAttachmentsForPackage.zip");

//Download all attachments for signer in package         
DownloadedFile downloadedAllAttachmentsForSigner1InPackage = client.getAttachmentRequirementService().downloadAllAttachmentFilesForSignerInPackage(myPackage, signer1);
Files.saveTo(downloadedAllAttachmentsForSigner1InPackage.getContents(), "downloadedAllAttachmentsForSigner.zip");

After reviewing the attachment, you have the ability to refuse or accept the attachment. In the latter situation, you can include feedback in the form of a small message explaining the refusal.

client.getAttachmentRequirementService().rejectAttachment(packageId, signer1, "Driver's license", "Expired driver's license");

It is important to note that packages with required attachments will not auto-complete. This is for the sender to have the opportunity to review the attachment and accept/reject it. If all the required attachments have been uploaded and approved, you can complete the package by updating the status of your package to COMPLETED.

DocumentPackage myPackage = client.getPackage(packageId);
		
myPackage.setStatus(PackageStatus.COMPLETED);
		
client.updatePackage(packageId, myPackage);

Running Your Code

Once you’ve run your code, if you log into OneSpan Sign and head to the signer settings in your package, you should find your attachment requests in the attachments tab.

attach

During the signing ceremony, the signer will be presented to the dialog below requesting to upload the required attachment.

ui_attachment_required

If you browse to your workspace directory, you will find your downloaded attachments.

downloaded_attachments

Get the Code | See this feature in action in our Interactive Demo

With OneSpan Sign, you have the ability to request attachments after your signer(s) signed your document(s). After the requested attachments have been provided, you will have the option of accepting or rejecting the attachment. In the event of a refusal, you will be able to provide feedback in the form of a short message and the signer will have the opportunity to upload a different file.

The Code

Below is a sample code on how you would edit your signer block to request a file attachment. The withDescription() method allows you to provide a description to the signer about the file upload you’re looking for and the isRequiredAttachment() method defines that you are requiring the attachment. Neither of these are mandatory when building your AttachmentRequirement object. If you need a comparison to the basic document object creation or if this is the first time creating a package (transaction in the new UI) with the .NET SDK, see this guide.

.WithSigner(SignerBuilder.NewSignerWithEmail("john.doe@gmail.com")
    .WithFirstName("John")
    .WithLastName("Doe")
    .WithCustomId("Signer1")
    .WithAttachmentRequirement(AttachmentRequirementBuilder.NewAttachmentRequirementWithName("Driver's license")
        .WithDescription("Please upload a copy of your driver’s license.")
        .IsRequiredAttachment()
        .Build()))

Accordingly, you may also want to query the status of each attachment in your package. OneSpan Sign will return AttachmentRequirement objects as a list. The code below will loop through each AttachmentRequirement object and print out the name, status, and id of each requested attachment for that particular signer.

DocumentPackage myPackage = client.GetPackage(packageId);

IList<AttachmentRequirement> signer1Attachments = myPackage.GetSigner("john.doe@gmail.com").Attachments;

foreach (AttachmentRequirement attachment in signer1Attachments)
{
     Debug.WriteLine(attachment.Name + " " + attachment.Status + " " + attachment.Id);
}

Furthermore, you have the option of downloading attachments in three different manners:

  • A single attachment (requires the attachment id)
  • All attachments in a package
  • All attachments from a particular signer
//Download individual attachment
DownloadedFile downloadedAttachment = client.AttachmentRequirementService.DownloadAttachmentFile(packageId, attachmentId);
System.IO.File.WriteAllBytes(downloadedAttachment.Filename, downloadedAttachment.Contents);

//Download all attachments in package
DownloadedFile downloadedAllAttachmentsForPackage = client.AttachmentRequirementService.DownloadAllAttachmentFilesForPackage(packageId);
System.IO.File.WriteAllBytes("downloadedAllAttachmentsForPackage.zip", downloadedAllAttachmentsForPackage.Contents);

//Download all attachments for signer in package
DownloadedFile downloadedAllAttachmentsForSigner1InPackage = client.AttachmentRequirementService.DownloadAllAttachmentFilesForSignerInPackage(myPackage, signer1);
System.IO.File.WriteAllBytes("downloadedAllAttachmentsForSigner.zip", downloadedAllAttachmentsForSigner1InPackage.Contents);

After reviewing the attachment, you have the ability to refuse or accept the attachment. In the latter situation, you can include feedback in the form of a small message explaining the refusal.

client.AttachmentRequirementService.RejectAttachment(packageId, signer1, "Driver's license", "Expired driver's license");

It is important to note that packages with required attachments will not auto-complete. This is for the sender to have the opportunity to review the attachment and accept/reject it. If all the required attachments have been uploaded and approved, you can complete the package by updating the status of your package to COMPLETED.

DocumentPackage myPackage = eslClient.GetPackage(packageId);

myPackage.Status = DocumentPackageStatus.COMPLETED;

eslClient.UpdatePackage(packageId, myPackage);

Running Your Code

Once you’ve run your code, if you log into eSignLive and head to the signer settings in your package, you should find your attachment requests in the attachments tab.

attach

During the signing ceremony, the signer will be presented to the dialog below requesting to upload the required attachment.

ui_attachment_required

If you browse to your workspace directory, you will find your downloaded attachments.

downloaded_attachments

Get the Code | See this feature in action in our Interactive Demo

With OneSpan Sign, you have the ability to request attachments after your signer(s) signed your document(s). After the requested attachments have been provided, you will have the option of accepting or rejecting the attachment. In the event of a refusal, you will be able to provide feedback in the form of a short message and the signer will have the opportunity to upload a different file.

The Code

The sample request below shows you how to add a recipient with an attachment requirement. If you need a comparison to the basic document object creation or if this is the first time creating a package (transaction in the new UI) with the REST API, see this guide.

HTTP Request
POST /api/packages/{packageId}/roles

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

Request Payload

{
  "id": "client",
  "type": "SIGNER",
  "index": 1,
  "attachmentRequirements": [
    {
      "description": "Please upload a scanned copy of your driver's license.",
      "required": true,
      "id": "lD6p5QnWk905",
      "status": "INCOMPLETE",
      "comment": "",
      "name": "Driver's license"
    }
  ],
  "signers": [
    {
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@gmail.com"
    }
  ],
  "name": "client"
}

For a complete description of each field, take a look at the JSON Properties section below.

Response Payload

{
    "id": "client",
    "data": null,
    "emailMessage": null,
    "attachmentRequirements": [
        {
            "status": "INCOMPLETE",
            "description": "Please upload a scanned copy of your driver's license.",
            "required": true,
            "id": "1JMGfs9xRDoD",
            "comment": "",
            "name": "Driver's license",
            "data": null
        }
    ],
    "locked": false,
    "reassign": false,
    "specialTypes": [],
    "index": 1,
    "type": "SIGNER",
    "signers": [
        {
            "group": null,
            "language": "en",
            "signature": null,
            "id": "fe666c24-c18d-4d93-bbb7-2b1a6ce8332e",
            "auth": {
                "scheme": "NONE",
                "challenges": []
            },
            "data": null,
            "title": "",
            "external": null,
            "updated": "2017-10-19T18:18:37Z",
            "company": "",
            "email": "john.smith@gmail.com",
            "firstName": "John",
            "lastName": "Smith",
            "phone": "",
            "professionalIdentityFields": [],
            "userCustomFields": [],
            "knowledgeBasedAuthentication": null,
            "delivery": {
                "provider": false,
                "email": false,
                "download": false
            },
            "address": null,
            "created": "2017-10-19T18:18:37Z",
            "name": "",
            "specialTypes": []
        }
    ],
    "name": "client"
}

To download an individual attachment, you will need the package and attachment id.

HTTP Request
GET /api/packages/{packageId}/attachment/{attachmentId}

HTTP Headers
Accept: application/octet-stream
Content-Type: application/octet-stream
Authorization: Basic api_key

Response Payload

[document.pdf]

To download all attachments as a zip file in a package, you will make your request to

HTTP Request
GET /api/packages/{packageId}/attachment/zip

HTTP Headers
Accept: application/zip
Content-Type: application/zip
Authorization: Basic api_key

Response Payload

[document.zip]

To download all attachments as a zip file for a particular signer, you will make your request to:

HTTP Request
GET /api/packages/{packageId}/attachment/zip/{roleId}

HTTP Headers
Accept: application/zip
Content-Type: application/zip
Authorization: Basic api_key

[document.zip]

After reviewing the attachment, you have the ability to accept or refuse the attachment. In the latter situation, you can include feedback in the form of a small message explaining the refusal. To refuse an attachment:

HTTP Request
PUT /api/packages/{packageId}/roles/{roleId}

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

Request Payload

{
  "attachmentRequirements": [
    {
      "id": "q66CYiDrxTU1",
      "status": "REJECTED",
      "comment": "Invalid copy."
    }
  ]
}

It is important to note that packages with required attachments will not auto-complete. This is for the sender to have the opportunity to review the attachment and accept/reject it. If all the required attachments have been uploaded and approved, you can complete the package by:

HTTP Request
PUT /api/packages/{packageId}/

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

Request Payload

{
    "status" : "COMPLETED"
}

Running Your Code

Once you’ve run your code, if you log into OneSpan Sign and head to the signer settings in your package, you should find your attachment requests in the attachments tab.

attach

During the signing ceremony, the signer will be presented to the dialog below requesting to upload the required attachment.

ui_attachment_required

If you browse to your workspace directory, you will find your downloaded attachments.

downloaded_attachments

Get the Code | See this feature in action in our Interactive Demo

JSON Properties

Property Type Editable Required Default Sample Value(s)
id string Yes No n/a client
type string Yes No SIGNER SIGNER / SENDER
index integer Yes No 0 0 / 1 / 2 …
name string Yes No n/a client
attachmentRequirements
description string Yes No n/a Please upload a scanned copy of your driver’s license
required boolean Yes No false false / true
id string Yes No n/a lD6p5QnWk905
status string Yes No INCOMPLETE INCOMPLETE / COMPLETE / REJECTED
comment string Yes No n/a wrong driver license
name string Yes No n/a Driver’s license
signers
firstName string Yes No n/a John
lastName string Yes No n/a Smith
email string Yes No n/a john.smith@gmail.com

With OneSpan Sign, you have the ability to request attachments during the signing ceremony. After the requested attachments have been provided, you will have the option of accepting or rejecting the attachment. In the event of a refusal, you will be able to provide feedback in the form of a short message and the signer will have the opportunity to upload a different file.
To notice, some of the code is an extension of the APEX SDK and can be gotten through the Code Share.

The Code

Below is a sample code on how you would create a role object requiring file attachments. If you need a comparison to the basic document object creation or if this is the first time creating a package (known as a transaction in the UI) with the Apex SDK, see this guide.

ESignLiveAPIObjects.Role role = new ESignLiveAPIObjects.Role();

ESignLiveAPIObjects.Signer signer = new ESignLiveAPIObjects.Signer();
signer.firstName = 'firstName';
signer.lastName = 'lastName';
signer.email = 'signer@example.com';
signer.name = 'signer1';
signer.id = 'signer1';
role.signers = new List<ESignLiveAPIObjects.Signer>{signer};

role.id = 'signer1';
role.attachmentRequirements = new ESignLiveAPIObjects.AttachmentRequirement(null, 'Please upload a copy of your driver\'s license.','attachment1','driver\'s license' ,true,null,null);

Additional, there are two encapsulated functions in the code share:

public ESignLiveAPIObjects.AttachmentRequirement createAttachmentRequirement(String id, String name, String description, Boolean isRequired)
public ESignLiveAPIObjects.Role createRoleWithAttachmentRequest(String id, String firstName, String lastName, String email, List attachmentRequirements)

The createAttachmentRequirement() function allows you to easily create an AttachmentRequirement object with a set of input parameters that allow you to provide a description for the signer about the file you’re requesting and to define whether the attachment is required.
And the createRoleWithAttachmentRequest() function provides an easier way to create role with a list of attachment requirements.

Accordingly, you may also want to query the status of each attachment in your package. You can use the below code to loop through all AttachmentRequirement objects and print out the name, status, and id of each requested attachment for that particular signer.

ESignLiveSDK sdk = new ESignLiveSDK();
//retrieve attachments' status
ESignLiveAPIObjects.Role retrievedRole1 = sdk.getRole(packageId,roleId);
for(ESignLiveAPIObjects.AttachmentRequirement attachment: retrievedRole1.attachmentRequirements){
     System.debug('Attachment: ' + attachment.id+ ' : ' + attachment.name + ' : ' + attachment.status);        
}

The code snippet is encapsulated in this function:

public void retrieveAttachmentsStatus(String packageId, String roleId)

Furthermore, you have the option of downloading attachments in three different manners:

  • A single attachment (requires the attachment id) which encapsulated in:
    public Blob downloadAttachmentFile(String packageId, String attachmentId)
  • All attachments in a package which encapsulated in:
    public Blob downloadAllAttachmentFilesForPackage(String packageId)
  • All attachments from a particular signer
//Download individual attachment
Blob downloadAttachmentFile = downloadAttachmentFile('packageId','attachmentId');

//Download all attachments in package	    
Blob downloadAttachmentFilesForPackage = downloadAllAttachmentFilesForPackage('packageId');

//Download all attachments for signer in package         
ESignLiveSDK sdk = new ESignLiveSDK();
String downloadAllAttachmentForSigner = sdk.downloadAllAttachmentFilesForSignerInPackage('packageId','roleId');

After reviewing the attachment, you have the ability to refuse or accept the attachment. In the latter situation, you can include feedback in the form of a small message explaining the refusal. These two functions are encapsulated as:

public void acceptAttachment(String packageId, String roleId, String attachmentName)
public void rejectAttachment(String packageId, String roleId, String attachmentName, String senderComment)

It is important to note that packages with required attachments will not auto-complete. This is for the sender to have the opportunity to review the attachment and accept/reject it. If all the required attachments have been uploaded and approved, you can complete the package by updating the status of your package to COMPLETED.

ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId);
pkg.status = ESignLiveAPIObjects.PackageStatus.COMPLETED;
sdk.updatePackage(pkg,packageId);  

Running Your Code

Once you’ve run your code, if you log into OneSpan Sign and head to the signer settings in your package, you should find your attachment requests in the attachments tab.
Capture
During the signing ceremony, the signer will be presented to the dialog below requesting to upload the required attachment.
Capture
If you browse to your workspace directory, you will find your downloaded attachments.
Capture

Get the Code | See this feature in action in our Interactive Demo