To download the full code sample see our Code Share site.

OneSpan Sign offers the ability for signers to upload attachments during the signing workflow. Senders can review the provided attachment and mark the transaction as complete. This topic describes how a sender can require the signer to upload an attachment to the transaction.

Creating an Attachment Request

The following code describes how to 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 are requesting. The isRequiredAttachment() method defines that the attachment is required. Neither of these are mandatory when building your AttachmentRequirement object.

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

Attachment Status

You may want to query the status of each attachment in your transaction. The following code will loop through each AttachmentRequirement object and print out the name, status, and id of each requested attachment for the specified signer.

DocumentPackage myPackage = client.getPackage(packageId);
		
List<AttachmentRequirement> signer1Attachments = myPackage.getSigner("[email protected]").getAttachmentRequirements();
		
for(AttachmentRequirement attachment : signer1Attachments){
      System.out.println(attachment.getName() + " " + attachment.getStatus() + " " + attachment.getId());
}

Downloading Attachments

Attachments can be downloaded in the following ways:

  • As a single attachment. This requires the attachment id.
  • In a package that includes all attachments.
  • In a package that includes all attachments from a specified signer.

The following code will do this:

//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");

Reviewing Attachments

After reviewing the attachment, you can then either refuse or accept it. If you refuse the attachment, you can calso include a small feedback message explaining why the attachment was refused. The following code will do this:

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

It is important to note that transactions that require attachments will not auto-complete. This gives the sender the opportunity to review the attachment, and either accept or 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. The following code will do this:

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

Results

Once you have completed this procedure, the required documents will be listed with each recipient.

attach

To download the full code sample see our Code Share site.

OneSpan Sign offers the ability for signers to upload attachments during the signing workflow. Senders can review the provided attachment and mark the transaction as complete. This topic describes how a sender can require the signer to upload an attachment to the transaction.

Creating an Attachment Request

The following code describes how to 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 are requesting. The isRequiredAttachment() method defines that the attachment is required. Neither of these are mandatory when building your AttachmentRequirement object.

.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()))

Attachment Status

You may want to query the status of each attachment in your transaction. The following code will loop through each AttachmentRequirement object and print out the name, status, and id of each requested attachment for the specified signer.

DocumentPackage myPackage = client.GetPackage(packageId);
IList<AttachmentRequirement> signer1Attachments = myPackage.GetSigner("[email protected]").Attachments;
foreach (AttachmentRequirement attachment in signer1Attachments)
{
     Debug.WriteLine(attachment.Name + " " + attachment.Status + " " + attachment.Id);
}

Downloading Attachments

Attachments can be downloaded in the following ways:

  • As a single attachment. This requires the attachment id.
  • In a package that includes all attachments.
  • In a package that includes all attachments from a specified signer.

The following code will do this:

//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);

Reviewing Attachments

After reviewing the attachment, you can then either refuse or accept it. If you refuse the attachment, you can calso include a small feedback message explaining why the attachment was refused. The following code will do this:

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

It is important to note that transactions that require attachments will not auto-complete. This gives the sender the opportunity to review the attachment, and either accept or 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. The following code will do this:

DocumentPackage myPackage = eslClient.GetPackage(packageId);
myPackage.Status = DocumentPackageStatus.COMPLETED;
eslClient.UpdatePackage(packageId, myPackage);

Results

Once you have completed this procedure, the required documents will be listed with each recipient.

attach

To download the full code sample see our Code Share site.

OneSpan Sign offers the ability for signers to upload attachments during the signing workflow. Senders can review the provided attachment and mark the transaction as complete. This topic describes how a sender can require the signer to upload an attachment to the transaction.

Creating an Attachment Request

The following code describes how to add a recipient with an attachment requirement.

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": "[email protected]"
    }
  ],
  "name": "client"
}

For a complete description of each field, see the Request Payload table 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": "[email protected]",
            "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"
}

Downloading Attachments

Attachments can be downloaded in the following ways:

  • As a single attachment. This requires the attachment id.
  • In a package that includes all attachments.
  • In a package that includes all attachments from a specified signer.

To download an individual attachment, you will need the package and attachment ID. The following code will do this:

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]

You can also download all attachments as a zip file in a package. The following code will do this:

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]

Reviewing Attachments

After reviewing the attachment, you can then either refuse or accept it. If you refuse the attachment, you can calso include a small feedback message explaining why the attachment was refused. The following code will do this:

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 transactions that require attachments will not auto-complete. This gives the sender the opportunity to review the attachment, and either accept or 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. The following code will do this:

HTTP Request

PUT /api/packages/{packageId}/

HTTP Headers

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

Request Payload

{
    "status" : "COMPLETED"
}

Results

Once you have completed this procedure, the required documents will be listed with each recipient.

attach

JSON Properties Table

PropertyTypeEditableRequiredDefaultSample Values
idstringYesNon/aclient
typestringYesNoSIGNERSIGNER / SENDER
indexintegerYesNo00 / 1 / 2 ...
namestringYesNon/aclient
attachmentRequirements
descriptionstringYesNon/aPlease upload a scanned copy of your driver's license
requiredbooleanYesNofalsefalse / true
idstringYesNon/alD6p5QnWk905
statusstringYesNoINCOMPLETEINCOMPLETE / COMPLETE / REJECTED
commentstringYesNon/awrong driver license
namestringYesNon/aDriver's license
signers
firstNamestringYesNon/aJohn
lastNamestringYesNon/aSmith
emailstringYesNon/a[email protected]

To download the full code sample see our Code Share site.

OneSpan Sign offers the ability for signers to upload attachments during the signing workflow. Senders can review the provided attachment and mark the transaction as complete. This topic describes how a sender can require the signer to upload an attachment to the transaction.

Creating an Attachment Request

The following code describes how to edit your signer block to request a file attachment.

ESignLiveAPIObjects.Role role = new ESignLiveAPIObjects.Role();
ESignLiveAPIObjects.Signer signer = new ESignLiveAPIObjects.Signer();
signer.firstName = 'firstName';
signer.lastName = 'lastName';
signer.email = '[email protected]';
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 withDescription() method allows you to provide a description to the signer about the file upload you are requesting. The isRequiredAttachment() method defines that the attachment is required. Neither of these are mandatory when building your AttachmentRequirement object.

The createAttachmentRequirement() function allows you to provide a description to the signer about the file upload you are requesting and if that attachment is required. The createRoleWithAttachmentRequest() function provides an easier way to create role with a list of attachment requirements.

Attachment Status

You may want to query the status of each attachment in your transaction. The following code will loop through each AttachmentRequirement object and print out the name, status, and id of each requested attachment for the specified 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)

Downloading Attachments

Attachments can be downloaded in the following ways:

  • As a single attachment. This requires the attachment id.
  • In a package that includes all attachments.
  • In a package that includes all attachments from a specified signer.

The following code will do this:

//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');

Reviewing Attachments

After reviewing the attachment, you can then either refuse or accept it. If you refuse the attachment, you can calso include a small feedback message explaining why the attachment was refused. The following code will do this:

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 transactions that require attachments will not auto-complete. This gives the sender the opportunity to review the attachment, and either accept or 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. The following code will do this:

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

Results

Once you have completed this procedure, the required documents will be listed with each recipient.

attach