Creates a signature session

Overview

This API creates a signature session, which enables your users to perform digital signatures without requiring you to implement a signature web page on your app.

To create a signature session, your app specifies a returnUrl and receives back a redirectUrl. Your app then redirects the user to the redirectUrl, where he will digitally sign documents. Once the process is complete, the user will be redirected back to your app on the returnUrl you specified when starting the session. A query parameter will be added to the returnUrl containing the signature session ID (?signatureSessionId=...). Then, your app parses the signature session ID on the query string and uses it to call APIs to fetch the documents signed by the user.

The session can either have predefined documents that the user must sign (passed on the Documents collection) or allow the user to upload his own documents (in this case, omit the Documents collection).

Showing the signature page on a new tab

The default behavior is for your app to provide a returnUrl, and then redirect the user to the returnUrl returned by this API with a HTTP redirection response (e.g. 303 See Other) or with a location.href = ... call on Javascript. By the end of the procedure, the user is redirected back to your app, all in a single browser tab.

Alternatively, you may want to display the signature page on a new tab. In this case, omit the returnUrl parameter when creating the session. Furthermore, you must open the tab with an HTML anchor tag with target="_blank", or with the window.open() function on Javascript. The tab will then be closed by the end of the process.

Background processing

By default, users are kept waiting while documents are processed before being redirected back to your application.

If you want to provide your users with a faster experience, turn on background processing by passing EnableBackgroundProcessing = true. In this case, users do not wait for documents to be processed. However, your application must be ready to handle the case of a signature session whose documents are not yet available for download.

Webhooks

You may configure your Rest PKI Core subscription to inform your app of any documents that are signed on signature sessions created by it. This way, you don't need to rely on users landing back on your page to detect that documents have been signed. Please refer to the Webhooks section for more information.

Disabling downloads

If you don't receive webhook notifications of documents signed, you might feel like the signature session process is not working reliably because some users simply download the signed documents and don't bother to stick around while they are redirected back to your app, denying it the chance to detect that documents have been signed. If you feel this is a problem for your case, you can disable the downloading of signed documents by passing DisableDownloads = true. Then, users will only be able to download documents through your app, and thus will be far less inclined to quit the process prematurely.

File name validation

If you want to validate the file names that are acceptable for users to upload, you can configure the acceptable file name pattern on your subscription's configuration to a regular expression conforming to your rules.

You can also configure a file name validation endpoint, an API implemented by your app that is called for each file selected by the user with the file's name and MIME type and returns whether the file should be acceptable or not (and, if not, a reason to be displayed to the user).