OneSpan Sign How To: Get Signer Status

Haris Haidary, May 4, 2016
Thumbnail

Lately, in the forums, I’ve noticed a number of questions regarding how to retrieve the signer status after the document package has been sent for signing. This is a perfectly legitimate question, as you probably would want keep track of the signing status of each of your signers within your application. Reasons for this may include sending a reminder to your signer(s) for a pending signature. In this blog, I will show you how you can retrieve the signer status in your document package.

Callback Event Notifications

The easiest way to retrieve the signer status would be to setup a listener and register for callback event notifications. For example, you could register for the following events: SIGNER_COMPLETE, PACKAGE_OPT_OUT, PACKAGE_DECLINE, or DOCUMENT_SIGNED.

The SIGNER_COMPLETE event is the notification you will receive once your signer has completed signing all documents in your document package. The PACKAGE_OPT_OUT and PACKAGE_DECLINE events are the notifications sent if your signer opted-out of the signing ceremony or declined it, respectively. Lastly, the DOCUMENT_SIGNED event is the notification you will receive when any document has been signed and/or any consent/disclosure agreement has been accepted in your package. You can find more information about each available event notification, here.

In my example below, I’ve setup a listener and registered for the DOCUMENT_SIGNED and SIGNER_COMPLETE event notifications.

esl_signer_complete_notification

With the information from these events returned to you from OneSpan Sign, such as package id, document id, and session user, you can easily update the status of your signer within your application. The session user is the custom/role id I’ve set to my signer. You can find more information about callback event notifications in this previous blog

OneSpan Sign Developer Community

OneSpan Sign Developer Community

Join the OneSpan Sign Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today

Audit Trail

You can also retrieve the signer status from the audit trail, which gives you a step-by-step documented history of any transaction for a document package. You can get this either through the SDKs/API. In my example, I’ve chosen to retrieve the audit trail for my package through REST. As you can see in the JSON response below, the audit events of type "Capture Signature" and "Confirm" mean that my signer has signed the document and confirmed his/her signature. The signer email is also provided, which you can use to update the status of your signer in your application.

{
  "package-id": "95b51072-c467-4f6c-bf87-980d066b1fd0",
  "audit-events": [
    {
      "type": "Login",
      "date-time": "2016-05-03 14:56:25",
      "target": "EMAIL_LINK",
      "user": "John Smith",
      "user-email": "[email protected]",
      "user-ip": "XX.XX.XXX.XXX",
      "data": ""
    },
    {
      "type": "Signing Session For Signer",
      "date-time": "2016-05-03 14:56:25",
      "target": "Customizing Signing Ceremony",
      "user": "John Smith",
      "user-email": "[email protected]",
      "user-ip": "XX.XX.XXX.XXX",
      "data": "Signing session to signer : [email protected](John Smith"
    },
    {
      "type": "View",
      "date-time": "2016-05-03 14:56:28",
      "target": "Cleaning Contract",
      "user": "John Smith",
      "user-email": "[email protected]",
      "user-ip": "XX.XX.XXX.XXX",
      "data": null
    },
    {
      "type": "Capture Signature",
      "date-time": "2016-05-03 14:56:33",
      "target": "Cleaning Contract",
      "user": "John Smith",
      "user-email": "[email protected]",
      "user-ip": "XX.XX.XXX.XXX",
      "data": "Approval: 5d4a21b3-5187-486a-9cbe-79d2b056bcc7"
    },
    {
      "type": "Confirm",
      "date-time": "2016-05-03 14:56:35",
      "target": "Cleaning Contract",
      "user": "John Smith",
      "user-email": "[email protected]",
      "user-ip": "XX.XX.XXX.XXX",
      "data": null
    }
  ]
}

You can find more information about the audit trail and how to retrieve it, here. If you have questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the developer community forums: https://developer.onespan.com. That's it from me. Thank you for reading! If you found this post helpful, please share it on Facebook, Twitter, or LinkedIn.

Haris Haidary
Junior Technical Evangelist
LinkedIn | Twitter