Opt-out and Declined Messages

This guide will show you how to retrieve the opt-out and declined messages.

If a signer opts out of the signing ceremony or declines to sign the documents, the signer will be prompted to enter a reason for doing so. As an integrated user, you can retrieve these messages.

The Code

You can download the complete example code from the Developer Community Code Share, here.

The first step is to create the PackageId object of your document package. Once you have your PackageId object, you call on your OneSpan Sign client with the packageId object as a parameter to retrieve the messages. Opt-out and declined messages are returned to you as a list.

EslClient client = new EslClient(key, url);
		
PackageId packageId = new PackageId("VMvbq5C0BIQaxCtG_8LlppDdj08=");		
DocumentPackage documentPackage = client.getPackage(packageId);
		
List<Message> messages = client.getPackage(packageId).getMessages();
System.out.println(documentPackage.getStatus().toString() + " reason : " + messages.get(0).getContent());

Running Your Code

Below is a screenshot of the console output you can expect once you’ve run your code.

Capture

Get the Code

If a signer opts out of the signing ceremony or declines to sign the documents, the signer will be prompted to enter a reason for doing so. As an integrated user, you can retrieve these messages.

The Code

You can download the complete example code from the Developer Community Code Share, here.

The first step is to create the PackageId object of your document package. Once you have your PackageId object, you call on your OneSpan Sign client with the packageId object as a parameter to retrieve the messages. Opt-out and declined messages are returned to you as a list.

EslClient client = new EslClient(key, url);
		
PackageId packageId = new PackageId("VMvbq5C0BIQaxCtG_8LlppDdj08=");
		
DocumentPackage documentPackage = client.GetPackage(packageId);
IList<Message> messages = client.GetPackage(packageId).Messages;
		
Debug.WriteLine(documentPackage.Status.ToString() + " reason : " + messages[0].Content);

Running Your Code

Below is a screenshot of the console output you can expect once you’ve run your code.

Capture

Get the Code

If a signer opts out of the signing ceremony or declines to sign the documents, the signer will be prompted to enter a reason for doing so. As an integrated user, you can retrieve these messages.

The Code

You can download the complete example code from the Developer Community Code Share, here.

To retrieve the opt-out and declined messages, you will first need to retrieve the package JSON:

HTTP Request
POST /api/packages/{packageId}

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

Response Payload

{
  "status": "OPTED_OUT",
  "roles": [
    {
      "id": "TE4gJQuFqNE5",
      "data": null,
      "emailMessage": {
        "content": ""
      },
      "locked": false,
      "reassign": false,
      "specialTypes": [],
      "attachmentRequirements": [],
      "type": "SENDER",
      "index": 0,
      "signers": [
        {
          "group": null,
          "language": "en",
          "signature": {
            "handdrawn": "AQAAADJI+a4cnf0t3Dlf0GqWJceCA+4AAwADAN8BAAADAAAAggPuAOgAAAACfyxAUkAlQCdAOUA6QDtAHEAtQBtACkAJQBVAFBIyfkA0QBVABkAYQCpAHEAtQC9ALkAtQDxAO0A6QEhAN0AlQCQyTjZAgEBwQIBAoFDSUOFQ8lDiUNJQ0lCiQHBAUCIXGVBSUCVQN1BJUDpQXVA9UE5QLlAuUDpQOVAkm1BhQLZAd0B7QFpAXUBPQTBAHkAdQAtAB2AmYBRgQmCAcJVwmHC5Mh42QFBAkECAQKBAsEDAQNBQ8VDyUPJQ81DTULRQg1ByUEGeIgQ6QDhAJ0AmQCZAFItwbHBtMhdBUCafUGJQcVCSUJFQoUDAQKBAsECBQHNAdEBEQDRABkAFYCdgR2BXYHhgd2CIYIVgdmBDYEJAUUBwQIFAkECwQLBA0EDAQLBAoEBwQGASG0xAc0BnQEhASkArQBxADEAKQAlABkAFMkVKUENQUVBBUGFQYVCRUKJQsVDCUNJQsUDQQKBAkEBwQFJAREAlIllVUHFQUVByUKFQslDSUNJQ9VDlUPZQ1lDWUKVQZVBEUCQyCxivr2BjYGRgdGB1YHZgZmBWYEdgRkAFQClAREBjQJNAk0CzQKNAs0CjQJNAQo9gRWBjYJNgs2DCYNRg1GCkYKRgY2Bkrg==",
            "textual": null
          },
          "id": "ZQI8k6faVoM8",
          "data": null,
          "title": null,
          "auth": {
            "scheme": "NONE",
            "challenges": []
          },
          "updated": "2018-05-02T15:55:42Z",
          "external": null,
          "knowledgeBasedAuthentication": null,
          "email": "mail44@mailinator.com",
          "firstName": "Haris",
          "lastName": "Haidary",
          "phone": "",
          "professionalIdentityFields": [],
          "userCustomFields": [],
          "company": "eSignLive",
          "delivery": {
            "download": true,
            "email": true,
            "provider": false
          },
          "address": null,
          "created": "2018-05-02T15:55:42Z",
          "name": "",
          "specialTypes": []
        }
      ],
      "name": "Owner"
    },
    {
      "id": "bf5ed1f3-54dc-4231-8548-e01878cda700",
      "data": null,
      "emailMessage": {
        "content": ""
      },
      "locked": false,
      "reassign": false,
      "specialTypes": [],
      "attachmentRequirements": [],
      "type": "SIGNER",
      "index": 0,
      "signers": [
        {
          "group": null,
          "language": "en",
          "signature": null,
          "id": "a8e907ec-9472-4cb9-812a-efe5af88ed1b",
          "data": null,
          "title": "",
          "auth": {
            "scheme": "NONE",
            "challenges": []
          },
          "updated": "2018-05-02T15:56:02Z",
          "external": null,
          "knowledgeBasedAuthentication": null,
          "email": "mai33@mailinator.com",
          "firstName": "john",
          "lastName": "smith",
          "phone": "",
          "professionalIdentityFields": [],
          "userCustomFields": [],
          "company": "",
          "delivery": {
            "download": false,
            "email": false,
            "provider": false
          },
          "address": null,
          "created": "2018-05-02T15:56:03Z",
          "name": "",
          "specialTypes": []
        }
      ],
      "name": "Signer1"
    },
    {
      "id": "b85551ee-6788-4468-9943-947a24b53d1e",
      "data": null,
      "emailMessage": {
        "content": ""
      },
      "locked": false,
      "reassign": false,
      "specialTypes": [],
      "attachmentRequirements": [],
      "type": "SIGNER",
      "index": 0,
      "signers": [
        {
          "group": null,
          "language": "en",
          "signature": null,
          "id": "530d4aa6-dc40-430f-a797-67ce030bd632",
          "data": null,
          "title": "",
          "auth": {
            "scheme": "NONE",
            "challenges": []
          },
          "updated": "2018-05-02T15:56:12Z",
          "external": null,
          "knowledgeBasedAuthentication": null,
          "email": "john_smith@mailinator.com",
          "firstName": "John",
          "lastName": "Smith",
          "phone": "",
          "professionalIdentityFields": [],
          "userCustomFields": [],
          "company": "",
          "delivery": {
            "download": false,
            "email": false,
            "provider": false
          },
          "address": null,
          "created": "2018-05-02T15:56:12Z",
          "name": "",
          "specialTypes": []
        }
      ],
      "name": "Signer2"
    }
  ],
  "description": "",
  "language": "en",
  "id": "-_MOT5yMI3Cx3S7OWaFGkrXzOw8=",
  "data": {
    "senderVisible": false,
    "currentSignerProgress": {
      "documentsToConfirmCount": "0",
      "documentsConfirmedCount": "0",
      "approvalsToConfirmCount": "0",
      "approvalsConfirmedCount": "0",
      "documentsPartiallyCompletedCount": "0",
      "approvalsToSignNowCount": "0"
    },
    "overallProgress": {
      "documentsToCompleteCount": "3",
      "documentsCompletedCount": "1",
      "documentsToConfirmCount": "3",
      "documentsConfirmedCount": "1",
      "documentsPartiallyCompletedCount": "0"
    }
  },
  "autocomplete": true,
  "completed": null,
  "sender": {
    "status": "ACTIVE",
    "language": "en",
    "signature": {
      "handdrawn": "AQAAADJI+a4cnf0t3Dlf0GqWJceCA+4AAwADAN8BAAADAAAAggPuAOgAAAACfyxAUkAlQCdAOUA6QDtAHEAtQBtACkAJQBVAFBIyfkA0QBVABkAYQCpAHEAtQC9ALkAtQDxAO0A6QEhAN0AlQCQyTjZAgEBwQIBAoFDSUOFQ8lDiUNJQ0lCiQHBAUCIXGVBSUCVQN1BJUDpQXVA9UE5QLlAuUDpQOVAkm1BhQLZAd0B7QFpAXUBPQTBAHkAdQAtAB2AmYBRgQmCAcJVwmHC5Mh42QFBAkECAQKBAsEDAQNBQ8VDyUPJQ81DTULRQg1ByUEGeIgQ6QDhAJ0AmQCZAFItwbHBtMhdBUCafUGJQcVCSUJFQoUDAQKBAsECBQHNAdEBEQDRABkAFYCdgR2BXYHhgd2CIYIVgdmBDYEJAUUBwQIFAkECwQLBA0EDAQLBAoEBwQGASG0xAc0BnQEhASkArQBxADEAKQAlABkAFMkVKUENQUVBBUGFQYVCRUKJQsVDCUNJQsUDQQKBAkEBwQFJAREAlIllVUHFQUVByUKFQslDSUNJQ9VDlUPZQ1lDWUKVQZVBEUCQyCxivr2BjYGRgdGB1YHZgZmBWYEdgRkAFQClAREBjQJNAk0CzQKNAs0CjQJNAQo9gRWBjYJNgs2DCYNRg1GCkYKRgY2Bkrg==",
      "textual": null
    },
    "id": "ZQI8k6faVoM8",
    "data": {
      "serviceCredentials": "{}",
      "showIntro": false
    },
    "account": {
      "id": "3vD0Dc9Fh7wQ",
      "data": null,
      "created": "2016-05-05T19:30:13Z",
      "logoAltTextKey": "",
      "updated": "2016-05-05T19:30:13Z",
      "company": {
        "id": "jVWmyg4cyis8",
        "data": null,
        "address": {
          "address1": null,
          "address2": null,
          "city": null,
          "country": null,
          "zipcode": null,
          "state": null
        },
        "name": "eSignLive"
      },
      "customFields": [
        {
          "required": false,
          "id": "Department",
          "data": null,
          "translations": [
            {
              "description": "GSA Division information",
              "language": "en",
              "id": "",
              "data": null,
              "name": "Department"
            }
          ],
          "value": "",
          "name": ""
        }
      ],
      "licenses": [
        {
          "status": "ACTIVE",
          "created": "2016-05-05T19:30:13Z",
          "paidUntil": "2020-05-05T00:00:00Z",
          "plan": {
            "group": "",
            "description": "E-Sign Hundreds of Documents with Unlimited Signers",
            "id": "sandbox",
            "data": null,
            "quotas": [
              {
                "cycle": null,
                "scope": "ACCOUNT",
                "limit": 100,
                "target": "SENDER"
              },
              {
                "cycle": null,
                "scope": "SENDER",
                "limit": 500,
                "target": "DOCUMENT"
              },
              {
                "cycle": null,
                "scope": "SENDER",
                "limit": 500,
                "target": "STORAGE"
              }
            ],
            "cycle": "YEAR",
            "contract": "YEAR",
            "freeCycles": null,
            "features": null,
            "original": null,
            "price": {
              "amount": 0,
              "currency": {
                "id": "USD",
                "data": null,
                "name": "US Dollar"
              }
            },
            "name": "Sandbox"
          },
          "transactions": []
        }
      ],
      "logoUrl": "",
      "providers": null,
      "owner": "ZQI8k6faVoM8",
      "name": "Haris Haidary"
    },
    "title": null,
    "updated": "2016-05-05T19:30:13Z",
    "external": null,
    "locked": null,
    "email": "mail44@mailinator.com",
    "firstName": "Haris",
    "lastName": "Haidary",
    "memberships": [],
    "phone": "+1 201-555-5555",
    "professionalIdentityFields": [],
    "userCustomFields": [
      {
        "id": "policy_number_id",
        "data": null,
        "translations": [],
        "value": "",
        "name": ""
      }
    ],
    "activated": null,
    "company": "eSignLive",
    "type": "MANAGER",
    "address": {
      "address1": "",
      "address2": "",
      "city": "",
      "country": "",
      "zipcode": "",
      "state": ""
    },
    "created": "2016-05-05T19:30:13Z",
    "name": "",
    "specialTypes": [],
    "hasDelegates": false
  },
  "documents": [
    {
      "status": "",
      "description": "Must be accepted and agreed to before starting the signing process.",
      "id": "default-consent",
      "data": {
        "ese_document_texttag_extract_needed": "false"
      },
      "approvals": [
        {
          "id": "d1f0b072-14b0-4bd8-8f0a-fcb53c38a4d7",
          "role": "bf5ed1f3-54dc-4231-8548-e01878cda700",
          "data": null,
          "signed": "2018-05-02T15:57:20Z",
          "accepted": "2018-05-02T15:57:20Z",
          "fields": [],
          "name": ""
        },
        {
          "id": "0d48f338-942c-4373-8b62-e6f4ed3e400b",
          "role": "b85551ee-6788-4468-9943-947a24b53d1e",
          "data": null,
          "signed": "2018-05-02T16:05:01Z",
          "accepted": "2018-05-02T16:05:01Z",
          "fields": [],
          "name": ""
        }
      ],
      "pages": [
        {
          "id": "",
          "top": 0,
          "height": 1030,
          "width": 796,
          "left": 0,
          "version": 0,
          "index": 0
        },
        {
          "id": "",
          "top": 0,
          "height": 1030,
          "width": 796,
          "left": 0,
          "version": 0,
          "index": 1
        }
      ],
      "external": null,
      "extract": false,
      "signedHash": null,
      "extractionTypes": [],
      "tagged": false,
      "signerVerificationToken": null,
      "index": 0,
      "fields": [],
      "name": "Electronic Disclosures and Signatures Consent",
      "size": 0
    },
    {
      "status": "",
      "description": "",
      "id": "01ea8c42e0443900006fd1ca13dd813764de134e379f9187",
      "data": {
        "ese_document_texttag_autofielddateformat": "yyyy-MM-dd HH:mm:ss 'GMT'",
        "ese_document_texttag_json_0": "[]",
        "ese_document_texttag_extract_needed": "true",
        "ese_document_texttag_handled_roles": "[]"
      },
      "approvals": [
        {
          "id": "ufcu7BEkPhQ7",
          "role": "bf5ed1f3-54dc-4231-8548-e01878cda700",
          "data": null,
          "signed": null,
          "accepted": null,
          "fields": [
            {
              "binding": null,
              "validation": null,
              "id": "NEUF14vd6uQP",
              "page": 0,
              "data": null,
              "subtype": "FULLNAME",
              "top": 220,
              "height": 37,
              "extractAnchor": null,
              "extract": false,
              "width": 165,
              "left": 315,
              "type": "SIGNATURE",
              "value": "",
              "name": ""
            }
          ],
          "name": ""
        },
        {
          "id": "m6X4vXnEnu0S",
          "role": "b85551ee-6788-4468-9943-947a24b53d1e",
          "data": null,
          "signed": null,
          "accepted": null,
          "fields": [
            {
              "binding": null,
              "validation": null,
              "id": "R8NmG0RgXGIU",
              "page": 0,
              "data": null,
              "subtype": "FULLNAME",
              "top": 267,
              "height": 37,
              "extractAnchor": null,
              "extract": false,
              "width": 165,
              "left": 315,
              "type": "SIGNATURE",
              "value": "",
              "name": ""
            }
          ],
          "name": ""
        }
      ],
      "pages": [
        {
          "id": "",
          "top": 0,
          "height": 1030,
          "width": 796,
          "left": 0,
          "version": 0,
          "index": 0
        }
      ],
      "external": null,
      "extract": true,
      "signedHash": null,
      "extractionTypes": [
        "TEXT_TAGS",
        "ACROFIELDS"
      ],
      "tagged": false,
      "signerVerificationToken": null,
      "index": 1,
      "fields": [],
      "name": "doc1",
      "size": 80054
    },
    {
      "status": "",
      "description": "",
      "id": "9fed8a66f25b2539bea003066148b56fccd67c7cd72c874a",
      "data": {
        "ese_document_texttag_autofielddateformat": "yyyy-MM-dd HH:mm:ss 'GMT'",
        "ese_document_texttag_json_0": "[]",
        "ese_document_texttag_extract_needed": "true",
        "ese_document_texttag_handled_roles": "[]"
      },
      "approvals": [
        {
          "id": "2e75dPZB1X0X",
          "role": "b85551ee-6788-4468-9943-947a24b53d1e",
          "data": null,
          "signed": null,
          "accepted": null,
          "fields": [
            {
              "binding": null,
              "validation": null,
              "id": "Yy9LGdjHwLEE",
              "page": 0,
              "data": null,
              "subtype": "FULLNAME",
              "top": 691,
              "height": 37,
              "extractAnchor": null,
              "extract": false,
              "width": 165,
              "left": 315,
              "type": "SIGNATURE",
              "value": "",
              "name": ""
            }
          ],
          "name": ""
        },
        {
          "id": "kj8n0eK5KV8T",
          "role": "bf5ed1f3-54dc-4231-8548-e01878cda700",
          "data": null,
          "signed": null,
          "accepted": null,
          "fields": [
            {
              "binding": null,
              "validation": null,
              "id": "7gY6IBFunFQI",
              "page": 0,
              "data": null,
              "subtype": "FULLNAME",
              "top": 737,
              "height": 37,
              "extractAnchor": null,
              "extract": false,
              "width": 165,
              "left": 315,
              "type": "SIGNATURE",
              "value": "",
              "name": ""
            }
          ],
          "name": ""
        }
      ],
      "pages": [
        {
          "id": "",
          "top": 0,
          "height": 1030,
          "width": 796,
          "left": 0,
          "version": 0,
          "index": 0
        }
      ],
      "external": null,
      "extract": true,
      "signedHash": null,
      "extractionTypes": [
        "TEXT_TAGS",
        "ACROFIELDS"
      ],
      "tagged": false,
      "signerVerificationToken": null,
      "index": 2,
      "fields": [],
      "name": "cleaning_contract",
      "size": 190472
    }
  ],
  "consent": "default-consent",
  "due": null,
  "emailMessage": "",
  "limits": null,
  "notarized": false,
  "notaryRoleId": null,
  "settings": {
    "ceremony": {
      "layout": {
        "header": {
          "breadcrumbs": true,
          "feedback": true,
          "globalActions": {
            "confirm": true,
            "download": true,
            "hideEvidenceSummary": true,
            "saveAsLayout": true
          },
          "globalNavigation": true,
          "sessionBar": true,
          "titleBar": null
        },
        "brandingBar": {
          "logo": {
            "link": "",
            "logoAltTextKey": "",
            "src": "branding"
          }
        },
        "footer": null,
        "iframe": false,
        "navigator": true
      },
      "extractTextTags": true,
      "extractAcroFields": true,
      "ada": false,
      "events": {
        "complete": {
          "redirect": "https://google.ca",
          "dialog": true
        }
      },
      "enforceCaptureSignature": false,
      "inPerson": false,
      "declineButton": true,
      "declineReasons": [],
      "disableDeclineOther": false,
      "disableDownloadForUncompletedPackage": false,
      "disableFirstInPersonAffidavit": false,
      "disableInPersonAffidavit": false,
      "disableOptOutOther": false,
      "disableSecondInPersonAffidavit": false,
      "documentToolbarOptions": null,
      "handOver": null,
      "hideCaptureText": false,
      "hideLanguageDropdown": false,
      "hidePackageOwnerInPerson": false,
      "hideWatermark": false,
      "maxAuthFailsAllowed": 3,
      "optOutButton": true,
      "optOutReasons": [],
      "style": null
    }
  },
  "signedDocumentDelivery": null,
  "trashed": false,
  "updated": "2018-05-04T19:13:21Z",
  "visibility": "ACCOUNT",
  "type": "PACKAGE",
  "created": "2018-05-02T15:55:42Z",
  "messages": [
    {
      "status": "NEW",
      "from": {
        "group": null,
        "language": "en",
        "signature": null,
        "id": "a8e907ec-9472-4cb9-812a-efe5af88ed1b",
        "data": null,
        "title": "",
        "auth": {
          "scheme": "NONE",
          "challenges": []
        },
        "updated": "2018-05-02T15:56:02Z",
        "external": null,
        "knowledgeBasedAuthentication": null,
        "email": "mai33@mailinator.com",
        "firstName": "john",
        "lastName": "smith",
        "phone": "",
        "professionalIdentityFields": [],
        "userCustomFields": [],
        "company": "",
        "delivery": {
          "download": false,
          "email": false,
          "provider": false
        },
        "address": null,
        "created": "2018-05-02T15:56:03Z",
        "name": "",
        "specialTypes": []
      },
      "content": "I do not wish to sign electronically.",
      "created": "2018-05-04T19:13:22Z",
      "to": [],
      "documents": []
    }
  ],
  "name": "test",
  "bulkSendable": false
}

Then, you can retrieve the messages from the “messages” key in the json response object.

Get the Code

If a signer opts out of the signing ceremony or declines to sign the documents, the signer will be prompted to enter a reason for doing so. As an integrated user, you can retrieve these messages.

The Code

The first step is to grab your Package Object by your Package ID. Once you have your Package object, you can retrieve the message list. After checking for null value, we can simply read the first message.

ESignLiveSDK sdk = new ESignLiveSDK();
ESignLiveAPIObjects.Package_x pkg = sdk.getPackage(packageId);
if(pkg.messages == null || pkg.messages.size() == 0){
        throw new ESignLiveRESTAPIHelper.ESignLiveRestAPIHelperException('Error retrieve Optout And Declined Messages');
}
ESignLiveAPIObjects.Message message = pkg.messages.get(0);
System.Debug(pkg.status.name() + ' reason: ' + message.content);

Running Your Code

Below is a screenshot of the console output you can expect once you’ve run your code.
Capture

Get the Code