Package Management

This guide shows you how to retrieve, update, archive and delete your packages in OneSpan Sign.

Following up on creating a document package, this guide will cover how to retrieve, update, archive and delete your document package.

The Code

To retrieve a package, you will first need to create a PackageId object using the id returned to you during package creation. Then, you can retrieve your package using the OneSpan Sign client and passing the PackageId object you just created as a parameter.

PackageId packageId = new PackageId("package_id_here");
DocumentPackage retrievedPkg = eslClient.getPackage(packageId);

You can also retrieve a list of packages/transactions.

Page<DocumentPackage> resultPage = eslClient.getPackageService().getPackages( new PackageStatusConverter(PackageStatus.SENT).toAPIPackageStatus(), new PageRequest(1, 10));

The call above will return the first 10 packages/transactions in status SENT. You can query the following statuses in OneSpan Sign: SENT, DRAFT, COMPLETED, OPTED_OUT, DECLINED, EXPIRED, and ARCHIVED.

To update an existing package that is in DRAFT status, simply create a document package object with only the updates you want to make to the package and then simply call the UpdatePackage function with the packageId of the existing package and the updates DocumentPackage:

DocumentPackage packageToUpdate = PackageBuilder.newPackageNamed(NEW_PACKAGE_NAME)
	              .describedAs(NEW_DESCRIPTION)
	              .withEmailMessage(NEW_EMAIL_MESSAGE)
	              .expiresAt(LocalDateTime.now().toDate())
	              .withLanguage(Locale.FRENCH)
	              .withVisibility(NEW_VISIBILITY)
	              .withNotarized(NEW_NOTARIZED)
	              .autocomplete(false)
	              .withSettings(settingsToUpdate)
	              .build();
	
eslClient.updatePackage(packageId, packageToUpdate);

If you want to remove a package from your account, permanently, simply call the deletePackage function with the packageId of the package you wish to delete.

eslClient.getPackageService().deletePackage(packageId);

If you might want to access this package in the future, you can move a package to your trash folder instead.

eslClient.getPackageService().trash(packageId);

Finally, to archive a package, simply call on the OneSpan Sign client with the packageId you wish to archive:

eslClient.getPackageService().archive(new PackageId("packageId"));

Get the Code

Following up on creating a document package, this guide will cover how to retrieve, update, archive and delete your document package.

The Code

To retrieve a package, you will first need to create a PackageId object using the id returned to you during package creation. Then, you can retrieve your package using the OneSpan Sign client and passing the PackageId object you just created as a parameter.

PackageId packageId = new PackageId("package_id_here");
DocumentPackage retrievedPkg = eslClient.GetPackage(packageId);

You can also retrieve a list of packages/transactions.

Page<DocumentPackage> packages = eslClient.PackageService.GetPackages (DocumentPackageStatus.SENT, new PageRequest(1, 10));

The call above will return the first 10 packages/transactions in status SENT. You can query the following statuses in OneSpan Sign: SENT, DRAFT, COMPLETED, OPTED_OUT, DECLINED, EXPIRED, and ARCHIVED.

To update an existing package that is in DRAFT status, simply create a document package object with only the updates you want to make to the package and then simply call the UpdatePackage function with the packageId of the existing package and the updates DocumentPackage:

DocumentPackage packageToUpdate = PackageBuilder.NewPackageNamed(NEW_PACKAGE_NAME)
                                .WithEmailMessage(NEW_EMAIL_MESSAGE)
                                .ExpiresOn(NEW_EXPIRY_DATE)
                                .WithLanguage(NEW_LANGUAGE)
                                .WithVisibility(NEW_VISIBILITY)
                                .WithNotarized(NEW_NOTARIZED)
                                .WithoutAutomaticCompletion()
                                .WithSettings(settingsToUpdate)
                                .Build();

eslClient.UpdatePackage(packageId, packageToUpdate);

If you want to remove a package from your account, permanently, simply call the DeletePackage function with the packageId of the package you wish to delete.

eslClient.PackageService.DeletePackage(packageId);

If you might want to access this package in the future, you can move a package to your trash folder instead.

eslClient.PackageService.Trash(packageId);

Finally, to archive a package, simply call on the OneSpan Sign client with the packageId you wish to archive:

eslClient.PackageService.Archive(new PackageId("packageId"));

Get the Code

Following up on creating a document package, this guide will cover how to retrieve, update, archive and delete your document package.

The Code

To retrieve a package (GET), update (PUT), or delete a package (DELETE), you will need to make your request to the following URL using the id returned to you during package creation:

https://sandbox.esignlive.com/api/packages/{packageId}

You can also retrieve a list of packages/transactions.

HTTP Request
GET /api/packages?from=0&to=10&query=SENT

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

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

Response Payload

{
  "results": [
    {
      "roles": [
        {
          "id": "6AMmJNBN5tYX",
          "emailMessage": null,
          "attachmentRequirements": [],
          "locked": false,
          "reassign": false,
          "specialTypes": [],
          "data": null,
          "index": 0,
          "type": "SENDER",
          "signers": [
            {
              "group": null,
              "language": "en",
              "signature": {
                "handdrawn": "",
                "textual": null
              },
              "id": "ZQI8k6faVoM8",
              "address": null,
              "created": "2017-11-01T14:16:56Z",
              "title": null,
              "external": null,
              "updated": "2017-11-01T14:16:56Z",
              "phone": "",
              "userCustomFields": [],
              "company": "eSignLive",
              "email": "mail45@mailinator.com",
              "firstName": "Haris",
              "lastName": "Haidary",
              "professionalIdentityFields": [],
              "data": null,
              "auth": {
                "scheme": "NONE",
                "challenges": []
              },
              "knowledgeBasedAuthentication": null,
              "delivery": {
                "email": true,
                "download": true,
                "provider": false
              },
              "name": "",
              "specialTypes": []
            }
          ],
          "name": "Owner"
        },
        {
          "id": "dc93cc7d-cebd-4767-a787-3726e7b2dda2",
          "emailMessage": null,
          "attachmentRequirements": [],
          "locked": false,
          "reassign": false,
          "specialTypes": [],
          "data": null,
          "index": 0,
          "type": "SIGNER",
          "signers": [
            {
              "group": null,
              "language": "en",
              "signature": null,
              "id": "7b90b5e1-08fd-4b98-977c-868850e72753",
              "address": null,
              "created": "2017-11-01T14:17:07Z",
              "title": "",
              "external": null,
              "updated": "2017-11-01T14:17:06Z",
              "phone": "",
              "userCustomFields": [],
              "company": "",
              "email": "mail22@mailinator.com",
              "firstName": "Patty",
              "lastName": "Galant",
              "professionalIdentityFields": [],
              "data": null,
              "auth": {
                "scheme": "NONE",
                "challenges": []
              },
              "knowledgeBasedAuthentication": null,
              "delivery": {
                "email": false,
                "download": false,
                "provider": false
              },
              "name": "",
              "specialTypes": []
            }
          ],
          "name": "Signer1"
        },
        {
          "id": "de96db97-121a-4630-9245-81e7f82e6bd2",
          "emailMessage": null,
          "attachmentRequirements": [],
          "locked": false,
          "reassign": false,
          "specialTypes": [],
          "data": null,
          "index": 0,
          "type": "SIGNER",
          "signers": [
            {
              "group": null,
              "language": "en",
              "signature": null,
              "id": "27067702-e47e-4d4d-9cd1-d14ffcf85fa1",
              "address": null,
              "created": "2017-11-01T14:17:12Z",
              "title": "",
              "external": null,
              "updated": "2017-11-01T14:17:11Z",
              "phone": "",
              "userCustomFields": [],
              "company": "",
              "email": "mail11@mailinator.com",
              "firstName": "John",
              "lastName": "Smith",
              "professionalIdentityFields": [],
              "data": null,
              "auth": {
                "scheme": "NONE",
                "challenges": []
              },
              "knowledgeBasedAuthentication": null,
              "delivery": {
                "email": false,
                "download": false,
                "provider": false
              },
              "name": "",
              "specialTypes": []
            }
          ],
          "name": "Signer2"
        }
      ],
      "status": "SENT",
      "description": "",
      "language": "en",
      "id": "-mFBc6RXIY3ZfwVj5nU_IPCH_0U=",
      "created": "2017-11-01T14:17:27Z",
      "autocomplete": true,
      "sender": {
        "status": "ACTIVE",
        "language": "en",
        "signature": {
          "handdrawn": "",
          "textual": null
        },
        "id": "ZQI8k6faVoM8",
        "address": null,
        "created": "2016-05-05T19:30:13Z",
        "title": null,
        "external": null,
        "updated": "2016-05-05T19:30:13Z",
        "memberships": [],
        "phone": "+1 201-555-5555",
        "userCustomFields": [
          {
            "id": "policy_number_id",
            "translations": [
              {
                "description": "Car Insurance Policy Number.",
                "language": "en",
                "id": "",
                "data": null,
                "name": "Policy Number"
              }
            ],
            "data": null,
            "value": "",
            "name": ""
          }
        ],
        "locked": null,
        "activated": null,
        "company": "eSignLive",
        "email": "mail46@mailinator.com",
        "firstName": "Haris",
        "lastName": "Haidary",
        "professionalIdentityFields": [],
        "account": null,
        "data": {
          "serviceCredentials": "{}",
          "showIntro": false
        },
        "type": "MANAGER",
        "name": "",
        "specialTypes": [],
        "hasDelegates": false
      },
      "documents": [
        {
          "status": "",
          "description": "",
          "id": "0c30c73e420bc00becf69a1bf312341263d4d6971a027d0d",
          "approvals": [
            {
              "role": "dc93cc7d-cebd-4767-a787-3726e7b2dda2",
              "id": "b4zp9Yzh6IoL",
              "signed": null,
              "accepted": null,
              "data": null,
              "fields": [
                {
                  "binding": null,
                  "validation": null,
                  "id": "4VXvP2KUMK4D",
                  "page": 0,
                  "subtype": "FULLNAME",
                  "height": 51.99999809265137,
                  "extract": false,
                  "width": 234.9996913802624,
                  "extractAnchor": null,
                  "left": 208.9996923339367,
                  "top": 489.99988202691077,
                  "data": null,
                  "type": "SIGNATURE",
                  "value": "",
                  "name": ""
                }
              ],
              "name": ""
            },
            {
              "role": "de96db97-121a-4630-9245-81e7f82e6bd2",
              "id": "UP3cifVBLZsS",
              "signed": null,
              "accepted": null,
              "data": null,
              "fields": [
                {
                  "binding": null,
                  "validation": null,
                  "id": "PHRegXF7w0wY",
                  "page": 0,
                  "subtype": "FULLNAME",
                  "height": 52.0252180917263,
                  "extract": false,
                  "width": 234.98929138064383,
                  "extractAnchor": null,
                  "left": 260.0935904598236,
                  "top": 596.586878117323,
                  "data": null,
                  "type": "SIGNATURE",
                  "value": "",
                  "name": ""
                }
              ],
              "name": ""
            }
          ],
          "pages": [
            {
              "id": "53659ae7eb53699b0e6027311a5b9db435984e896e1306cf_0_-1_1.png",
              "height": 1030,
              "left": 0,
              "width": 796,
              "top": 0,
              "index": 0,
              "version": 0
            }
          ],
          "external": null,
          "extract": false,
          "data": {},
          "signedHash": null,
          "extractionTypes": [],
          "signerVerificationToken": null,
          "fields": [],
          "index": 0,
          "name": "sample_contract",
          "size": 97332
        }
      ],
      "completed": null,
      "consent": null,
      "due": null,
      "emailMessage": "",
      "limits": null,
      "notarized": false,
      "notaryRoleId": null,
      "settings": {
        "ceremony": {
          "layout": {
            "header": {
              "feedback": true,
              "breadcrumbs": true,
              "globalActions": {
                "confirm": true,
                "download": true,
                "hideEvidenceSummary": true,
                "saveAsLayout": true
              },
              "globalNavigation": true,
              "titleBar": null,
              "sessionBar": true
            },
            "brandingBar": {
              "logo": {
                "link": "",
                "src": "branding"
              }
            },
            "iframe": false,
            "footer": null,
            "navigator": true
          },
          "inPerson": true,
          "declineButton": true,
          "declineReasons": [],
          "disableDeclineOther": false,
          "disableDownloadForUncompletedPackage": false,
          "disableFirstInPersonAffidavit": false,
          "disableInPersonAffidavit": false,
          "disableOptOutOther": false,
          "disableSecondInPersonAffidavit": false,
          "documentToolbarOptions": null,
          "events": {
            "complete": {
              "dialog": true,
              "redirect": null
            }
          },
          "handOver": null,
          "hideCaptureText": false,
          "hideLanguageDropdown": false,
          "hidePackageOwnerInPerson": false,
          "hideWatermark": false,
          "maxAuthFailsAllowed": 3,
          "optOutButton": true,
          "optOutReasons": [],
          "extractAcroFields": false,
          "extractTextTags": false,
          "style": null,
          "enforceCaptureSignature": false
        }
      },
      "signedDocumentDelivery": null,
      "trashed": false,
      "updated": "2017-11-01T14:17:27Z",
      "visibility": "ACCOUNT",
      "data": {
        "senderVisible": false,
        "currentSignerProgress": {
          "documentsToConfirmCount": "0",
          "documentsConfirmedCount": "0",
          "approvalsToConfirmCount": "0",
          "approvalsConfirmedCount": "0",
          "documentsPartiallyCompletedCount": "0",
          "approvalsToSignNowCount": "0"
        },
        "overallProgress": {
          "documentsToCompleteCount": "1",
          "documentsCompletedCount": "0",
          "documentsToConfirmCount": "1",
          "documentsConfirmedCount": "0",
          "documentsPartiallyCompletedCount": "0"
        }
      },
      "messages": [],
      "type": "PACKAGE",
      "name": "in-person switch",
      "bulkSendable": false
    }
  ],
  "count": 30
}

The call above will return the first 10 packages/transactions in status SENT. You can query the following statuses in OneSpan Sign: SENT, DRAFT, COMPLETED, OPTED_OUT, DECLINED, EXPIRED, and ARCHIVED.

To update an existing package that is in DRAFT status, simply create a payload with only the updates you want to make to the package and make your PUT request:

HTTP Request
PUT /api/packages/{packageId}

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

Request Payload

{
  "due": "2017-02-13T21:18:40Z",
  "emailMessage": "new email message",
  "notarized": true,
  "settings": {
    "ceremony": {
      "inPerson": false,
      "declineButton": true,
      "declineReasons": [
        "new decline reason #1",
        "new decline reason #2",
        "new decline reason #3"
      ],
      "disableDeclineOther": false,
      "disableDownloadForUncompletedPackage": false,
      "disableFirstInPersonAffidavit": false,
      "disableInPersonAffidavit": false,
      "disableOptOutOther": false,
      "disableSecondInPersonAffidavit": false,
      "documentToolbarOptions": {
        "downloadButton": false
      },
      "events": {
        "complete": {
          "dialog": false,
          "redirect": ""
        }
      },
      "handOver": {
        "href": "http://www.new.ca",
        "title": "new hand over link tool tip",
        "text": "new hand over link text"
      },
      "hideCaptureText": true,
      "hideLanguageDropdown": false,
      "hidePackageOwnerInPerson": false,
      "hideWatermark": true,
      "maxAuthFailsAllowed": 3,
      "optOutButton": false,
      "optOutReasons": [
        "new opt out reason #1",
        "new opt out reason #2",
        "new opt out reason #3"
      ],
      "layout": {
        "brandingBar": {
          "logo": {
            "src": "new logo image source",
            "link": "new logo image link"
          }
        },
        "footer": {},
        "iframe": false,
        "navigator": false,
        "header": {
          "feedback": true,
          "breadcrumbs": false,
          "titleBar": {
            "progressBar": false,
            "title": false
          },
          "globalActions": {
            "confirm": false,
            "download": false,
            "hideEvidenceSummary": true,
            "saveAsLayout": false
          },
          "globalNavigation": false,
          "sessionBar": false
        }
      },
      "style": null
    }
  },
  "description": "",
  "autocomplete": false,
  "visibility": "ACCOUNT",
  "status": "DRAFT",
  "type": "PACKAGE",
  "roles": [
    {
      "reassign": false,
      "locked": false,
      "index": 0,
      "type": "SENDER",
      "signers": [
        {
          "title": null,
          "address": null,
          "phone": "",
          "firstName": "Haris",
          "lastName": "Haidary",
          "email": "mail45@mailinator.com",
          "company": "eSignLive",
          "language": "fr",
          "name": ""
        }
      ],
      "name": "Owner"
    }
  ],
  "language": "fr",
  "name": "new package name",
  "bulkSendable": false
}

If you want to remove a package from your account, permanently, simply make a DELETE request. If on the other hand, you might want to access this package in the future, you can move a package to your trash folder instead by making a PUT request with the following payload:

HTTP Request
PUT /api/packages/{packageId}

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

Request Payload

{
  "trashed": true
}

Finally, to archive a package, simply update the status of the package to ARCHIVED:

HTTP Request
PUT /api/packages/{packageId}

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

Request Payload

{
  "status": "ARCHIVED"
}

Get the Code

JSON Properties

Property Type Editable Required Default Sample Value(s)
status string Yes No DRAFT DRAFT / SENT / COMPLETED / ARCHIVED / DECLINED / OPTED_OUT / EXPIRED
due string Yes Yes null 2017-02-13T21:18:40Z
emailMessage string Yes Yes null new email message
notarized boolean Yes Yes false true / false
description string Yes Yes null Sample transaction from STU BANK
autoComplete boolean Yes No true true / false
type string Yes No PACKAGE PACKAGE / TEMPLATE / LAYOUT
name string Yes Yes n/a Document Attributes Example
trashed boolean Yes No false true / false
language string Yes Yes en en / fr / es …
visibility string Yes No ACCOUNT ACCOUNT / SENDER
bulkSendable boolean Yes No false false / true
roles
id string Yes No n/a Client1
index integer Yes No 0 0 / 1 / 2 …
reassign boolean Yes No false false / true
locked boolean Yes No false false / true
name string Yes No n/a Client1
type string Yes No SIGNER SIGNER / SENDER
signers
email string Yes Yes n/a preparer.email@example.com
firstName string Yes Yes n/a John
lastName string Yes Yes n/a Smith
phone string Yes No n/a 514-555-8888
id string Yes No n/a Client1
company string Yes No n/a Acme Inc.
address string Yes No n/a 123 Main St.
title string Yes No n/a Managing Director
settings
ceremony
inPerson boolean Yes No false false / true
declineButton boolean Yes No true false / true
declineReasons string Yes No n/a new decline reason #1
optOutReasons string Yes No n/a new opt-out reason #1
disableDeclineOther boolean Yes No false false / true
disableDownloadForUncompletedPackage boolean Yes No false false / true
disableFirstInPersonAffidavit boolean Yes No false false / true
disableInPersonAffidavit boolean Yes No false false / true
disableOptOutOther boolean Yes No false false / true
disableSecondInPersonAffidavit boolean Yes No false false / true
hideCaptureText boolean Yes No false false / true
hideLanguageDropdown boolean Yes No false false / true
hidePackageOwnerInPerson boolean Yes No false false / true
hideWatermark boolean Yes No false false / true
maxAuthFailsAllowed integer Yes No 3 1 / 2 / 3 …
optOutButton boolean Yes No false false / true
layout
iframe boolean Yes No false false / true
navigator boolean Yes No false false / true
header
feedback boolean Yes No false false / true
breadcrumbs boolean Yes No false false / true
globalNavigation boolean Yes No false false / true
sessionBar boolean Yes No false false / true
titleBar
progressBar boolean Yes No false false / true
titleBar boolean Yes No false false / true
globalActions
confirm boolean Yes No false false / true
download boolean Yes No false false / true
hideEvidenceSummary boolean Yes No false false / true
saveAsLayout boolean Yes No false false / true
brandingBar
logo
src string Yes No null new logo image source
link string Yes No null new logo image link
events
complete
dialog boolean Yes No false true / false
redirect string Yes No null https://www.google.ca
handOver
href string Yes No null http://www.new.ca
title string Yes No null new hand over link tool tip
text string Yes No null new hand over link text

Following up on creating a document package, this guide will cover how to retrieve, update, archive and delete your document package.

To notice, some of the code is an extension of the APEX SDK and can be gotten through this Code Share.

The Code

To retrieve a package, you can call below function by passing the package ID you just created as a parameter.

//retrieve a package
ESignLiveSDK sdk = new ESignLiveSDK();
ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId);

You can also retrieve a list of packages/transactions, this function is encapsulated like below:

public List<ESignLiveAPIObjects.Package_x> getPackages(Map<String,String> queryParameters)

You can pass a map of query parameters in order to narrow your search like this:

List<ESignLiveAPIObjects.Package_x> pkgs = getPackages(new Map<String,String>{'from'=>'0','to'=>'9','status'=>'SENT'});

The call above will return the first 10 packages/transactions in status SENT. You can query the following statuses in OneSpan Sign: SENT, DRAFT, COMPLETED, OPTED_OUT, DECLINED, EXPIRED, and ARCHIVED.

Refer to this Document Page for all potential query parameters.

To update an existing package that is in DRAFT status, you can either grab the existing package object and do changes on that or simply create a package object with only the updates you want to make to the package, then simply call the updatePackage() function with the package ID of the existing package and the updates Package_x object:

//update package
ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId); //or
ESignLiveAPIObjects.Package_x pkg = new ESignLiveAPIObjects.Package_x();
pkg.name = 'changed package name';
sdk.updatePackage(pkg, packageId);

If you want to remove a package from your account, permanently, simply call the deletePackage () function with the package ID of the package you wish to delete.

//delete package
sdk.deletePackage(packageId); 

If you might want to access this package in the future, you can move a package to your trash folder instead.

//trash package
ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId);
pkg.trashed = true;    
sdk.updatePackage(pkg, packageId);

Finally, to archive a package, simply call setStatus() function with package ID you wish to archive:

//archive package
sdk.setStatus(packageId, ESignLiveAPIObjects.PackageStatus.ARCHIVED);	//you can only archive completed packages
sdk.setStatus(packageId, ESignLiveAPIObjects.PackageStatus.COMPLETED); //restore archive

Get the Code