# The electronic signature life cycle
# Using DocumentService and the SOAP APIs
# 1. Uploading the documents
The first step is to upload the documents that you want the end-user to sign to Signicat's standalone Session Data Storage (SDS).
# 2. Create a signing request
The signing request is a SOAP request sent to DocumentService API. This is where you specify which signing methods should be available to sign with, the documents that should be signed and other options for the signing flow.
Requests are made up of five main components:
# 3. Redirect the user to Signicat for the signing request
After the signing request has been created and you want the user to sign the document, you need to construct a URL that takes the user to Signicat's electronic signature solution.
# URL format
The URL will have the following format:
| || || ||Yes|
| || || ||Yes|
| || ||Yes|
| || ||Yes|
| || ||No|
All URL parameters must be properly URL-encoded using UTF-8, as per RFC 3986.
Example of a valid signing URL: https://preprod.signicat.com/std/docaction/demo?request_id=10112015xwufkg8j94nfikhn0t26mvmme13mqzd37ok0tn5pv9am9y4hl&task_id=task0
For a code example of a simple request using C# or Java, see our code examples for creating a signing order with one signer.
# Request workflow and task order
The order in which the tasks of signature request are completed can be arranged by using
depends-on-task within the
Task datatype, allowing for complex workflows. For example: Two customers and a sales person need to sign a contract, but the sales person may only sign when both of the customers have completed their signatures.
In this scenario the request would consist of three tasks (one for each signer), so lets call these tasks A, B and C.
- The first option is to let the two customers sign in parallel. This would be achieved by letting task C depend on task A and B.
- Alternatively, all signatures could be sequential. This could be achieved by letting task B depend on A and task C depend on B.
# Changing an existing request
There could be various reasons why you would want to change an existing request — the email address or mobile number of one of the signers could have changed, the relevant signers could change or the request could simply become obsolete.
- Existing requests can be deleted by using deleteRequest.
- Notifications can be disabled and new notifications can be added to an existing request by using disableNotification and addNotification.
- Tasks can be disabled and new ones added to existing requests by using disableTask and addTask.
# 4. Receive status of the request
When the signing order was created, you most likely defined a
documentactionrequest in order for notifications and callbacks to notify your server (or other recipient) about actions being taken by the signer — whether it's a request being created, cancelled or completed.
We provide three complementary mechanisms for this:
- Notification by redirect
- Notification by server-to-server callback
- Notification by messaging
All are optional and may be used independently.
# Notification by redirect
When you're creating a signing order, the
documentactionrequest allows you to specify three different URLs where Signicat can redirect the end-user when they have signed (or declined to sign) a document. These cover the following scenarios:
|URL||URL is used when|
| ||The URL where the end-user should be returned if the task is cancelled.|
| ||The URL where the end-user should be returned if they choose to postpone the task.|
| ||The URL where the end-user should be returned when the task is completed.|
The URLs are specified for each signing order and may contain HTTP parameters with session-specific or transaction-specific values. The end-user will not be redirected at all if
on-task-complete is missing in the request when a document has been signed.
HTTP redirection cannot be guaranteed, however, the end-user may close their browser before the redirect has completed or network problems may prevent the HTTP request to reach your server.
# Notification by server-to-server callback
documentactionrequest allows you to specify a URL on your server that Signicat should call when a signing order is created or completed.
Signicat's server will make an HTTPS call to this URL directly (or HTTP, but insecure HTTP calls are only supported in pre-production). This is a server-to-server call, not involving the end-user's browser at all.
You may specify a static URL that should be used for all signing orders or you may specify a different URL for each order. The URL may contain any number of parameters, such as session-specific parameters or user-specific information. You may also add parameters for added security, such as a static or dynamic password. Signicat will always add the
requestId in an extra HTTP parameter.
The HTTP call will be made by Signicat's server and will come from a fixed IP address. In order for these to work, Signicat must be informed about the destination address on your end, as our firewall blocks notifications to unknown URLs by default.
The notification is specified in the request with these values:
| ||The string "URL"|
| ||The URL that Signicat should call (with any HTTP parameters).|
You may specify more than one notification if you want Signicat to make more than one callback. Delivery of the notification is guaranteed as long as your server is able to receive HTTP calls.
When doing server-to-server notification, you may choose to add additional security features to make the notification reliable. An example would be to:
- Create a one time token (a random number or string) for each request.
- Add the token to the callback URL in an HTTP parameter called
- Validate that the value of the parameter is correct when Signicat makes the callback.
The steps above will protect against fake HTTP callbacks, since senders of fake callbacks would not be able to guess the correct parameter value.
# Notification by messaging
documentactionrequest allows you to specify a mobile phone number or an email address where Signicat should send a message when a signing order is created or completed — you may specify one or more notifications like this.
Typical use cases for this would be to send a message to a back office address, send a message to the end-user or even send a message to a local workflow system.
Each message is specified in each request and the text can be personalised or contain user-specific information like customer number, transaction details and so forth. Delivery of the notification depends on the SMS and email infrastructure and cannot be guaranteed.
The notification is specified in the
documentactionrequest with these values:
| ||The sender address.|
| ||Subject in email. Not used for SMS.|
| ||The text message in the email or SMS.|
| ||The string "SMS" or "EMAIL".|
| ||Phone number (with country code prefix) or email address.|
An example can be found here: Notify and get notified when a signing order status changes.
# Notes about security
You should not depend on the correctness of the information you receive in the notifications. The notifications should be regarded as a "hint" about a possible status change in the signing order. You must always call
getStatus on Signicat's web service after you have received a notification to get reliable, updated status information.
The "Notification by server-to-server" callback can be extended to include security mechanisms that would make the notification reliable. However, Signicat still recommends that you always call
getStatus to get reliable information. The information you receive in return from the
getStatus web service call will always be correct and reliable.
# Other web service calls
It is possible to get information about existing requests by using getStatus and getRequestHistory, which in combination yield a precise picture of any given requests as well as related status events.
An example of this can be found here: Check the status and result of a signing order.
getStatus can be used for checking status on selected request, but in general, polling should be avoided. Instead, notifications and callbacks should be used.
# 5. Signing result
Go to the next step, The signing result to learn more about what the signed document looks like and which formats you can choose.